1AUTOGEN(1) Programmer's Manual AUTOGEN(1)
2
3
4
6 autogen - The Automated Program Generator
7
9 autogen [-flag [value]]... [--opt-name [[=| ]value]]...
10 [ <def-file> ]
11
12 AutoGen creates text files from templates using external definitions.
13
15 This manual page documents, briefly, 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
22 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
31 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
39 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
44 -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
48 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
52 -l tpl-file, --lib-template=tpl-file
53 Library template file. This option may appear an unlimited num‐
54 ber of times.
55
56 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
60 -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
64 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
77 --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
83 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
90 -S file, --load-scheme=file
91 Scheme code file to load.
92
93 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
100 -F file, --load-functions=file
101 Load scheme function library.
102
103 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
110 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
122 getdefs load=getdefs.cfg <<source-file-list>>
123
124 Note, however, that your functions must be named:
125
126 name_of_some_group_scm_<<function_name>>(...)
127
128 so you may wish to use a shorter group name.
129
130 -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
135 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
140 -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
145 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
150 --source-time, --no-source-time
151 set mod times to latest source. The no-source-time form will
152 disable the option.
153
154 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
160 -m, --no-fmemopen
161 Do not use in-mem streams.
162
163 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
171 --equate=char-list
172 characters considered equivalent. The default char-list for
173 this option is:
174 _-^
175
176 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
181 --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
186 This option will leave output files writable. Normally, output
187 files are read-only.
188
189 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
198 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
204 -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
209 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
213 The valid range is 0 to 3600 seconds (1 hour). Zero will dis‐
214 able the server time limit.
215
216 --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 server-shell templates
222 block-macros expressions everything
223
224 The default level for this option is:
225 nothing
226
227 This option will cause AutoGen to display a trace of its tem‐
228 plate processing. There are six levels, each level including
229 messages from the previous levels:
230
231
232 nothing Does no tracing at all (default)
233
234
235 server-shell Traces all input and output to the server shell.
236 This includes a shell "independent" initialization script about
237 30 lines long. Its output is discarded and not inserted into
238 any template.
239
240
241 templates Traces the invocation of DEFINEd macros and INCLUDEs
242
243
244 block-macros Traces all block macros. The above, plus IF, FOR,
245 CASE and WHILE.
246
247
248 expressions Displays the results of expression evaluations.
249
250
251 everything Displays the invocation of every AutoGen macro, even
252 TEXT macros (i.e. the text outside of macro quotes).
253
254 --trace-out=file
255 tracing output file or filter.
256
257 The output specified may be either a file name, or, if the
258 option argument begins with the pipe operator (|), a command
259 that will receive the tracing output as standard in. For exam‐
260 ple, --traceout='| less' will run the trace output through the
261 less program.
262
263 --show-defs
264 Show the definition tree. This option may not be preset with
265 environment variables or in initialization (rc) files.
266
267 This will print out the complete definition tree before process‐
268 ing the template.
269
270 These options can be used to control what gets processed
271 in the definitions files and template files."
272
273 -D value, --define=value
274 name to add to definition list. This option may appear an
275 unlimited number of times.
276
277 The AutoGen define names are used for the following purposes:
278
279
280 Sections of the AutoGen definitions may be enabled or disabled
281 by using C-style #ifdef and #ifndef directives.
282
283 When defining a value for a name, you may specify the index for
284 a particular value. That index may be a literal value, a define
285 option or a value #define-d in the definitions themselves.
286
287 The name of a file may be prefixed with $NAME/. The $NAME part
288 of the name string will be replaced with the define-d value for
289 NAME.
290
291 When AutoGen is finished loading the definitions, the defined
292 values are exported to the environment with, putenv(3). These
293 values can then be used in shell scripts with ${NAME@} refer‐
294 ences and in templates with (getenv "NAME").
295
296 While processing a template, you may specify an index to
297 retrieve a specific value. That index may also be a define-d
298 value.
299
300 -U name-pat, --undefine=name-pat
301 definition list removal pattern. This option may appear an
302 unlimited number of times. This option may not be preset with
303 environment variables or in initialization (rc) files.
304
305 Just like 'C', AutoGen uses #ifdef/#ifndef preprocessing direc‐
306 tives. This option will cause the matching names to be removed
307 from the list of defined values.
308
309 The following options are commonly used and are provided and supported
310 by AutoOpts:"
311
312 -h, --short-help
313 Get short help text without an error exit. This option may not
314 be preset with environment variables or in initialization (rc)
315 files.
316
317 This option specifies that the abbreviated usage text should be
318 emitted.
319
320 -?, --help
321 Display usage information and exit.
322
323 -!, --more-help
324 Extended usage information passed thru pager.
325
326 -> [rcfile], --save-opts[=rcfile]
327 Save the option state to rcfile. The default is the last con‐
328 figuration file listed in the OPTION PRESETS section, below.
329
330 -< rcfile, --load-opts=rcfile, --no-load-opts
331 Load options from rcfile. The no-load-opts form will disable
332 the loading of earlier RC/INI files. --no-load-opts is handled
333 early, out of order.
334
335 -v [{v|c|n}], --version[={v|c|n}]
336 Output version of program and exit. The default mode is `v', a
337 simple version. The `c' mode will print copyright information
338 and `n' will print the full copyright notice.
339
341 Any option that is not marked as not presettable may be preset by load‐
342 ing values from configuration ("RC" or ".INI") file(s) and values from
343 environment variables named:
344 AUTOGEN_<option-name> or AUTOGEN
345 The environmental presets take precedence (are processed later than)
346 the configuration files. The homerc files are "$HOME", and ".". If
347 any of these are directories, then the file .autogenrc is searched for
348 within those directories.
349
351 This program is documented more fully in the AutoGen Info system docu‐
352 mentation.
353
354
356 autogen -T man.tpl --base-name=autogen opts.def
357
358
359 This command produced this man page from the AutoGen option definition
360 file. It overrides the template specified in opts.def (normally
361 options.tpl) and uses man.tpl. It also overrides the base-name of the
362 output file, which is normally derived from the input definition file
363 name (viz. opts).
364
366 Bruce Korb
367 Please send bug reports to: autogen-users@lists.sourceforge.net
368
369
370 Released under the GNU General Public License.
371
372 This manual page was AutoGen-erated from the autogen option defini‐
373 tions.
374
375
376
377(GNU AutoGen 5.8.9) 2007-02-15 AUTOGEN(1)