1AUTOGEN(1) Programmer's Manual AUTOGEN(1)
2
6 autogen - The Automated Program Generator
7
9 autogen [-flag [value]]... [--opt-name [[=| ]value]]...
10 [ <def-file> ]
11 AutoGen creates text files from templates using external definitions.
13
15 This manual page briefly documents the autogen command. AutoGen is
16 designed for generating program files that contain repetitive text with
17 varied substitutions. The goal is to simplify the maintenance of pro‐
18 grams that contain large amounts of repetitious text. This is espe‐
19 cially valuable if there are several blocks of such text that must be
20 kept synchronized.
21 One common example is the problem of maintaining the code required for
23 processing program options. Processing options requires a minimum of
24 four different constructs be kept in proper order in different places
25 in your program. You need at least: The flag character in the flag
26 string, code to process the flag when it is encountered, a global state
27 variable or two, and a line in the usage text. You will need more
28 things besides this if you choose to implement long option names,
29 rc/ini file processing, environment variables and so on.
30 All of this can be done mechanically; with the proper templates and
32 this program.
33
35 -L dir, --templ-dirs=dir
36 Template search directory list. This option may appear an
37 unlimited number of times.
38 Add a directory to the list of directories to search when open‐
40 ing a template, either as the primary template or an included
41 one. The last entry has the highest priority in the search
42 list. That is to say, they are searched in reverse order.
43 -T tpl-file, --override-tpl=tpl-file
45 Override template file. This option may not be preset with
46 environment variables or in initialization (rc) files.
47 Definition files specify the standard template that is to be
49 expanded. This option will override that name and expand a dif‐
50 ferent template.
51 -l tpl-file, --lib-template=tpl-file
53 Library template file. This option may appear an unlimited num‐
54 ber of times.
55 DEFINE macros are saved from this template file for use in pro‐
57 cessing the main macro file. Template text aside from the
58 DEFINE macros is is ignored.
59 -b name, --base-name=name
61 Base name for output file(s). This option may not be preset
62 with environment variables or in initialization (rc) files.
63 A template may specify the exact name of the output file. Nor‐
65 mally, it does not. Instead, the name is composed of the base
66 name of the definitions file with suffixes appended. This
67 option will override the base name derived from the definitions
68 file name. This is required if there is no definitions file and
69 advisable if definitions are being read from stdin. If the def‐
70 initions are being read from standard in, the base name defaults
71 to stdin. Any leading directory components in the name will be
72 silently removed. If you wish the output file to appear in a
73 particular directory, it is recommended that you "cd" into that
74 directory first, or use directory names in the format specifica‐
75 tion for the output suffix lists, @xref{pseudo macro}.
76 --definitions=file, --no-definitions
78 Definitions input file. The no-definitions form will disable
79 the option. This option is enabled by default. This option may
80 not be preset with environment variables or in initialization
81 (rc) files.
82 Use this argument to specify the input definitions file with a
84 command line option. If you do not specify this option, then
85 there must be a command line argument that specifies the file,
86 even if only to specify stdin with a hyphen (-). Specify, --no-
87 definitions when you wish to process a template without any
88 active AutoGen definitions.\n
89 -S file, --load-scheme=file
91 Scheme code file to load.
92 Use this option to pre-load Scheme scripts into the Guile inter‐
94 preter before template processing begins. Please note that the
95 AutoGen specific functions are not loaded until after argument
96 processing. So, though they may be specified in lambda func‐
97 tions you define, they may not be invoked until after option
98 processing is complete.
99 -F file, --load-functions=file
101 Load scheme function library.
102 This option is used to load Guile-scheme functions. The auto‐
104 matically called initialization routine scm_init must be used to
105 register these routines or data. This routine can be generated
106 by using the following command and the `snarf.tpl' template.
107 Read the introductory comment in `snarf.tpl' to see what the
108 `getdefs(1AG)' comment must contain.
109 First, create a config file for getdefs, and then invoke getdefs
111 loading that file:
112 cat > getdefs.cfg <<EOF
113 subblock exparg=arg_name,arg_desc,arg_optional,arg_list
114 defs-to-get gfunc
115 template snarf
116 srcfile
117 linenum
118 assign group = name_of_some_group
119 assign init = _init
120 EOF
121 getdefs load=getdefs.cfg <<source-file-list>>
123 Note, however, that your functions must be named:
125 name_of_some_group_scm_<<function_name>>(...)
127 so you may wish to use a shorter group name.
129 -s suffix, --skip-suffix=suffix
131 Omit the file with this suffix. This option may appear an
132 unlimited number of times. This option may not be preset with
133 environment variables or in initialization (rc) files.
134 Occasionally, it may not be desirable to produce all of the out‐
136 put files specified in the template. (For example, only the .h
137 header file, but not the .c program text.) To do this specify
138 --skip-suffix=c on the command line.
139 -o suffix, --select-suffix[=suffix]
141 specify this output suffix. This option may appear an unlimited
142 number of times. This option may not be preset with environment
143 variables or in initialization (rc) files.
144 If you wish to override the suffix specifications in the tem‐
146 plate, you can use one or more copies of this option. See the
147 suffix specification in the @ref{pseudo macro} section of the
148 info doc.
149 --source-time, --no-source-time
151 set mod times to latest source. The no-source-time form will
152 disable the option.
153 If you stamp your output files with the `DNE' macro output, then
155 your output files will always be different, even if the content
156 has not really changed. If you use this option, then the modi‐
157 fication time of the output files will change only if the input
158 files change. This will help reduce unneeded builds.
159 -m, --no-fmemopen
161 Do not use in-mem streams.
162 If the local C library supports "fopencookie(3GNU)", or
164 "funopen(3BSD)" then AutoGen prefers to use in-memory stream
165 buffer opens instead of anonymous files. This may lead to prob‐
166 lems if there is a shortage of virtual memory. If, for a par‐
167 ticular application, you run out of memory, then specify this
168 option. This is unlikely in a modern virtual memory environ‐
169 ment.
170 --equate=char-list
172 characters considered equivalent. The default char-list for
173 this option is:
174 _-^
175 This option will alter the list of characters considered equiva‐
177 lent. The default are the three characters, "_-^". (The last
178 is conventional on a Tandem/HP-NonStop, and I used to do a lot
179 of work on Tandems.)
180 --writable, --not-writable
182 Allow output files to be writable. The not-writable form will
183 disable the option. This option may not be preset with environ‐
184 ment variables or in initialization (rc) files.
185 This option will leave output files writable. Normally, output
187 files are read-only.
188 The following options are often useful while debugging new templates:
190 --loop-limit=lim
191 Limit on increment loops. This option takes an integer number
192 as its argument. The value of lim is constrained to being:
193 exactly -1, or
194 in the range 1 through 0x1000000
195 The default lim for this option is:
196 256
197 This option prevents runaway loops. For example, if you acci‐
199 dentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)",
200 it will take a long time to finish. If you do have more than
201 256 entries in tables, you will need to specify a new limit with
202 this option.
203 -t time-lim, --timeout=time-lim
205 Time limit for servers. This option takes an integer number as
206 its argument. The value of time-lim is constrained to being:
207 in the range 0 through 3600
208 AutoGen works with a shell server process. Most normal commands
210 will complete in less than 10 seconds. If, however, your com‐
211 mands need more time than this, use this option.
212 The valid range is 0 to 3600 seconds (1 hour). Zero will dis‐
214 able the server time limit.
215 --trace=level
217 tracing level of detail. This option takes a keyword as its
218 argument. The argument sets an enumeration value that can be
219 tested by comparing them against the option value macro. The
220 available keywords are:
221 nothing debug-message server-shell
222 templates block-macros expressions
223 everything
224 The default level for this option is:
226 nothing
227 This option will cause AutoGen to display a trace of its tem‐
229 plate processing. There are six levels, each level including
230 messages from the previous levels:
231 nothing Does no tracing at all (default)
234 debug-message Print messages from the "DEBUG" AutoGen macro
237 (@pxref{DEBUG}).
238 server-shell Traces all input and output to the server shell.
241 This includes a shell "independent" initialization script about
242 30 lines long. Its output is discarded and not inserted into
243 any template.
244 templates Traces the invocation of DEFINEd macros and INCLUDEs
247 block-macros Traces all block macros. The above, plus IF, FOR,
250 CASE and WHILE.
251 expressions Displays the results of expression evaluations.
254 everything Displays the invocation of every AutoGen macro, even
257 TEXT macros (i.e. the text outside of macro quotes). Addition‐
258 ally, if you rebuild the ``expr.ini'' file with debugging
259 enabled, then all calls to AutoGen defined scheme functions will
260 also get logged:
261 cd ${top_builddir}/agen5
262 DEBUG_ENABLED=true bash bootstrap.dir expr.ini
263 make CFLAGS='-g -DDEBUG_ENABLED=1'
264 Be aware tha tyou cannot rebuild this source in this way without
266 first having installed the autogen executable in your search
267 path. Because of this, "expr.ini" is in the distributed source
268 list, and not in the dependencies.
269 --trace-out=file
271 tracing output file or filter.
272 The output specified may be either a file name, or, if the
274 option argument begins with the pipe operator (|), a command
275 that will receive the tracing output as standard in. For exam‐
276 ple, --traceout='| less' will run the trace output through the
277 less program.
278 --show-defs
280 Show the definition tree. This option may not be preset with
281 environment variables or in initialization (rc) files.
282 This will print out the complete definition tree before process‐
284 ing the template.
285 These options can be used to control what gets processed
287 in the definitions files and template files."
288 -D value, --define=value
290 name to add to definition list. This option may appear an
291 unlimited number of times.
292 The AutoGen define names are used for the following purposes:
294 Sections of the AutoGen definitions may be enabled or disabled
297 by using C-style #ifdef and #ifndef directives.
298 When defining a value for a name, you may specify the index for
300 a particular value. That index may be a literal value, a define
301 option or a value #define-d in the definitions themselves.
302 The name of a file may be prefixed with $NAME/. The $NAME part
304 of the name string will be replaced with the define-d value for
305 NAME.
306 When AutoGen is finished loading the definitions, the defined
308 values are exported to the environment with, putenv(3). These
309 values can then be used in shell scripts with ${NAME@} refer‐
310 ences and in templates with (getenv "NAME").
311 While processing a template, you may specify an index to
313 retrieve a specific value. That index may also be a define-d
314 value.
315 -U name-pat, --undefine=name-pat
317 definition list removal pattern. This option may appear an
318 unlimited number of times. This option may not be preset with
319 environment variables or in initialization (rc) files.
320 Just like 'C', AutoGen uses #ifdef/#ifndef preprocessing direc‐
322 tives. This option will cause the matching names to be removed
323 from the list of defined values.
324 -?, --help
326 Display usage information and exit.
327 -!, --more-help
329 Extended usage information passed thru pager.
330 -> [rcfile], --save-opts[=rcfile]
332 Save the option state to rcfile. The default is the last con‐
333 figuration file listed in the OPTION PRESETS section, below.
334 -< rcfile, --load-opts=rcfile, --no-load-opts
336 Load options from rcfile. The no-load-opts form will disable
337 the loading of earlier RC/INI files. --no-load-opts is handled
338 early, out of order.
339 -v [{v|c|n}], --version[={v|c|n}]
341 Output version of program and exit. The default mode is `v', a
342 simple version. The `c' mode will print copyright information
343 and `n' will print the full copyright notice.
344
346 Any option that is not marked as not presettable may be preset by load‐
347 ing values from configuration ("RC" or ".INI") file(s) and values from
348 environment variables named:
349 AUTOGEN_<option-name> or AUTOGEN
350 The environmental presets take precedence (are processed later than)
351 the configuration files. The homerc files are "$HOME", and ".". If
352 any of these are directories, then the file .autogenrc is searched for
353 within those directories.
354
356 This program is documented more fully in the AutoGen Info system docu‐
357 mentation.
358
361 autogen -T man.tpl --base-name=autogen opts.def
362 This command produced this man page from the AutoGen option definition
365 file. It overrides the template specified in opts.def (normally
366 options.tpl) and uses man.tpl. It also overrides the base-name of the
367 output file, which is normally derived from the input definition file
368 name (viz. opts).
369
371 Bruce Korb
372 Please send bug reports to: autogen-users@lists.sourceforge.net
373 Released under the GNU General Public License.
376 This manual page was AutoGen-erated from the autogen option defini‐
378 tions.
379(GNU AutoGen 5.9.4) 2008-02-27 AUTOGEN(1)