1autogen(1) User Commands autogen(1)
2
6 autogen - The Automated Program Generator
7
9 autogen [-flag [value]]... [--opt-name[[=| ]value]]... [ <def-file> ]
10 AutoGen creates text files from templates using external definitions.
12
14 AutoGen is designed for generating program files that contain repeti‐
15 tive text with varied substitutions. The goal is to simplify the main‐
16 tenance of programs that contain large amounts of repetitious text.
17 This is especially valuable if there are several blocks of such text
18 that must be kept synchronized.
19 One common example is the problem of maintaining the code required for
21 processing program options. Processing options requires a minimum of
22 four different constructs be kept in proper order in different places
23 in your program. You need at least: The flag character in the flag
24 string, code to process the flag when it is encountered, a global state
25 variable or two, and a line in the usage text. You will need more
26 things besides this if you choose to implement long option names, con‐
27 figuration file processing, environment variables and so on.
28 All of this can be done mechanically; with the proper templates and
30 this program.
31
33 The following options select definitions, templates and scheme functions to
34 use
35 -L dir, --templ-dirs=dir
36 Search for templates in DIR. This option may appear an unlim‐
37 ited number of times.
38 Add a directory to the list of directories autogen searches when
40 opening a template, either as the primary template or an
41 included one. The last entry has the highest priority in the
42 search list. That is to say, they are searched in reverse
43 order.
44 -T tpl-file, --override-tpl=tpl-file
46 Use TPL-FILE for the template. This option may not be preset
47 with environment variables or in initialization (rc) files.
48 Definition files specify the standard template that is to be
50 expanded. This option will override that name and expand a dif‐
51 ferent template.
52 -l tpl-file, --lib-template=tpl-file
54 Load AutoGen macros from TPL-FILE. This option may appear an
55 unlimited number of times.
56 DEFINE macros are saved from this template file for use in pro‐
58 cessing the main macro file. Template text aside from the
59 DEFINE macros is is ignored.
60 Do not use this. Instead, use the INCLUDE macro in your tem‐
62 plate.
63 NOTE: THIS OPTION IS DEPRECATED
65 --definitions=file, --no-definitions
67 Read definitions from FILE. The no-definitions form will dis‐
68 able the option. This option is enabled by default. This
69 option may not be preset with environment variables or in ini‐
70 tialization (rc) files.
71 Use this argument to specify the input definitions file with a
73 command line option. If you do not specify this option, then
74 there must be a command line argument that specifies the file,
75 even if only to specify stdin with a hyphen (-). Specify, --no-
76 definitions when you wish to process a template without any
77 active AutoGen definitions.
78 --shell=shell
80 name or path name of shell to use.
81 By default, when AutoGen is built, the configuration is probed
83 for a reasonable Bourne-like shell to use for shell script pro‐
84 cessing. If a particular template needs an alternate shell, it
85 must be specified with this option on the command line, with an
86 environment variable (SHELL) or in the configuration/initializa‐
87 tion file.
88 -m, --no-fmemopen
90 Do not use in-mem streams.
91 If the local C library supports "fopencookie(3GNU)", or
93 "funopen(3BSD)" then AutoGen prefers to use in-memory stream
94 buffer opens instead of anonymous files. This may lead to prob‐
95 lems if there is a shortage of virtual memory. If, for a par‐
96 ticular application, you run out of memory, then specify this
97 option. This is unlikely in a modern 64-bit virtual memory
98 environment.
99 On platforms without these functions, the option is accepted but
101 ignored. fmemopen(POSIX) is not adequate because its string
102 buffer is not reallocatable. open_memstream(POSIX) is also not
103 adequate because the stream is only opened for output. AutoGen
104 needs a reallocatable buffer available for both reading and
105 writing.
106 --equate=char-list
108 characters considered equivalent. The default char-list for
109 this option is:
110 _-^
111 This option will alter the list of characters considered equiva‐
113 lent. The default are the three characters, "_-^". (The last
114 is conventional on a Tandem/HP-NonStop, and I used to do a lot
115 of work on Tandems.)
116 The following options modify how output is handled
118 -b name, --base-name=name
119 Specify NAME as the base name for output. This option may not
120 be preset with environment variables or in initialization (rc)
121 files.
122 A template may specify the exact name of the output file. Nor‐
124 mally, it does not. Instead, the name is composed of the base
125 name of the definitions file with suffixes appended. This
126 option will override the base name derived from the definitions
127 file name. This is required if there is no definitions file and
128 advisable if definitions are being read from stdin. If the def‐
129 initions are being read from standard in, the base name defaults
130 to stdin. Any leading directory components in the name will be
131 silently removed. If you wish the output file to appear in a
132 particular directory, it is recommended that you "cd" into that
133 directory first, or use directory names in the format specifica‐
134 tion for the output suffix lists, see: pseudo macro.
135 --source-time, --no-source-time
137 set mod times to latest source. The no-source-time form will
138 disable the option.
139 If you stamp your output files with the DNE macro output, then
141 your output files will always be different, even if the content
142 has not really changed. If you use this option, then the modi‐
143 fication time of the output files will change only if the input
144 files change. This will help reduce unneeded builds.
145 --writable, --not-writable
147 Allow output files to be writable. The not-writable form will
148 disable the option.
149 This option will leave output files writable. Normally, output
151 files are read-only.
152 The following options are often useful while debugging new templates
154 They specify limits that prevent the template from taking overly long
155 or producing more output than expected.
156 --loop-limit=lim
158 Limit on increment loops. This option takes an integer number
159 as its argument. The value of lim is constrained to being:
160 exactly -1, or
161 in the range 1 through 0x1000000
162 The default lim for this option is:
163 256
164 This option prevents runaway loops. For example, if you acci‐
166 dentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)",
167 it will take a long time to finish. If you do have more than
168 256 entries in tables, you will need to specify a new limit with
169 this option.
170 -t seconds, --timeout=seconds
172 Limit server shell operations to SECONDS. This option takes an
173 integer number as its argument. The value of seconds is con‐
174 strained to being:
175 in the range 0 through 3600
176 AutoGen works with a shell server process. Most normal commands
178 will complete in less than 10 seconds. If, however, your com‐
179 mands need more time than this, use this option.
180 The valid range is 0 to 3600 seconds (1 hour). Zero will dis‐
182 able the server time limit.
183 --trace=level
185 tracing level of detail. This option takes a keyword as its
186 argument. The argument sets an enumeration value that can be
187 tested by comparing them against the option value macro. The
188 available keywords are:
189 nothing debug-message server-shell
190 templates block-macros expressions
191 everything
192 or their numeric equivalent.
193 The default level for this option is:
195 nothing
196 This option will cause AutoGen to display a trace of its tem‐
198 plate processing. There are six levels, each level including
199 messages from the previous levels:
200 nothing Does no tracing at all (default)
203 debug-message Print messages from the "DEBUG" AutoGen macro
206 (see: DEBUG).
207 server-shell Traces all input and output to the server shell.
210 This includes a shell "independent" initialization script about
211 30 lines long. Its output is discarded and not inserted into
212 any template.
213 templates Traces the invocation of DEFINEd macros and INCLUDEs
216 block-macros Traces all block macros. The above, plus IF, FOR,
219 CASE and WHILE.
220 expressions Displays the results of expression evaluations.
223 everything Displays the invocation of every AutoGen macro, even
226 TEXT macros (i.e. the text outside of macro quotes). Addition‐
227 ally, if you rebuild the ``expr.ini'' file with debugging
228 enabled, then all calls to AutoGen defined scheme functions will
229 also get logged:
230 cd ${top_builddir}/agen5
231 DEBUG_ENABLED=true bash bootstrap.dir expr.ini
232 make CFLAGS='-g -DDEBUG_ENABLED=1'
233 Be aware that you cannot rebuild this source in this way without
235 first having installed the autogen executable in your search
236 path. Because of this, "expr.ini" is in the distributed source
237 list, and not in the dependencies.
238 --trace-out=file
240 tracing output file or filter.
241 The output specified may be a file name, a file that is appended
243 to, or, if the option argument begins with the pipe operator
244 (|), a command that will receive the tracing output as standard
245 in. For example, --traceout='| less' will run the trace output
246 through the less program. Appending to a file is specified by
247 preceeding the file name with two greater-than characters (>>).
248 --show-defs
250 Show the definition tree. This option may not be preset with
251 environment variables or in initialization (rc) files.
252 This will print out the complete definition tree before process‐
254 ing the template.
255 --used-defines
257 Show the definitions used. This option may not be preset with
258 environment variables or in initialization (rc) files.
259 This will print out the names of definition values searched for
261 during the processing of the template, whether actually found or
262 not. There may be other referenced definitions in a template in
263 portions of the template not evaluated. Some of the names
264 listed may be computed names and others AutoGen macro arguments.
265 This is not a means for producing a definitive, all-encompassing
266 list of all and only the values used from a definition file.
267 This is intended as an aid to template documentation only.
268 -C, --core
270 Leave a core dump on a failure exit.
271 Many systems default to a zero sized core limit. If the system
273 has the sys/resource.h header and if this option is supplied,
274 then in the failure exit path, autogen will attempt to set the
275 soft core limit to whatever the hard core limit is. If that
276 does not work, then an administrator must raise the hard core
277 size limit.
278 These options can be used to control what gets processed
280 in the definitions files and template files" They specify which outputs
281 and parts of outputs to produce.
282 -s suffix, --skip-suffix=suffix
284 Skip the file with this SUFFIX. This option may appear an
285 unlimited number of times. This option may not be preset with
286 environment variables or in initialization (rc) files. This
287 option must not appear in combination with any of the following
288 options: select-suffix.
289 Occasionally, it may not be desirable to produce all of the out‐
291 put files specified in the template. (For example, only the .h
292 header file, but not the .c program text.) To do this specify
293 --skip-suffix=c on the command line.
294 -o suffix, --select-suffix=suffix
296 specify this output suffix. This option may appear an unlimited
297 number of times. This option may not be preset with environment
298 variables or in initialization (rc) files.
299 If you wish to override the suffix specifications in the tem‐
301 plate, you can use one or more copies of this option. See the
302 suffix specification in the @ref{pseudo macro} section of the
303 info doc.
304 -D value, --define=value
306 name to add to definition list. This option may appear an
307 unlimited number of times.
308 The AutoGen define names are used for the following purposes:
310 Sections of the AutoGen definitions may be enabled or disabled
313 by using C-style #ifdef and #ifndef directives.
314 When defining a value for a name, you may specify the index for
316 a particular value. That index may be a literal value, a define
317 option or a value #define-d in the definitions themselves.
318 The name of a file may be prefixed with $NAME/. The $NAME part
320 of the name string will be replaced with the define-d value for
321 NAME.
322 When AutoGen is finished loading the definitions, the defined
324 values are exported to the environment with, putenv(3). These
325 values can then be used in shell scripts with ${NAME@} refer‐
326 ences and in templates with (getenv "NAME").
327 While processing a template, you may specify an index to
329 retrieve a specific value. That index may also be a define-d
330 value.
331 It is entirely equivalent to place this name in the exported
333 environment. Internally, that is what AutoGen actually does
334 with this option.
335 -U name-pat, --undefine=name-pat
337 definition list removal pattern. This option may appear an
338 unlimited number of times. This option may not be preset with
339 environment variables or in initialization (rc) files.
340 Similar to 'C', AutoGen uses #ifdef/#ifndef preprocessing direc‐
342 tives. This option will cause the matching names to be removed
343 from the list of defined values.
344 This option is used to automate dependency tracking
346 -M type, --make-dep[=type]
347 emit make dependency file. This option may appear an unlimited
348 number of times. This option may not be preset with environment
349 variables or in initialization (rc) files.
350 This option behaves fairly closely to the way the -M series of
352 options work with the gcc compiler, except that instead of just
353 emitting the predecessor dependencies, this also emits the suc‐
354 cessor dependencies (output target files). By default, the out‐
355 put dependency information will be placed in <base-name>.d, but
356 may also be specified with -MF<file>. The time stamp on this
357 file will be manipulated so that it will be one second older
358 than the oldest primary output file.
359 The target in this dependency file will normally be the depen‐
361 dency file name, but may also be overridden with -MT<targ-name>.
362 AutoGen will not alter the contents of that file, but it may
363 create it and it will adjust the modification time to match the
364 start time.
365 NB: these second letters are part of the option argument, so -MF
367 <file> must have the space character quoted or omitted, and -M
368 "F <file>" is acceptable because the F is part of the option
369 argument.
370 -M may be followed by any of the letters M, F, P, T, Q, D, or G.
372 However, only F, Q, T and P are meaningful. All but F have
373 somewhat different meanings. -MT<name> is interpreted as mean‐
374 ing <name> is a sentinel file that will depend on all inputs
375 (templates and definition files) and all the output files will
376 depend on this sentinel file. It is suitable for use as a real
377 make target. Q is treated identically to T, except dollar char‐
378 acters ('$') are doubled. P causes a special clean (clobber)
379 phoney rule to be inserted into the make file fragment. An
380 empty rule is always created for building the list of targets.
381 This is the recommended usage:
383 -MFwhatever-you-like.dep -MTyour-sentinel-file -MP
384 and then in your Makefile, make the autogen rule:
385 -include whatever-you-like.dep
386 clean_targets += clean-your-sentinel-file
387 .sp
388 your-sentinel-file:
389 autogen -MT$@@ -MF$*.d .....
390 .sp
391 local-clean :
392 rm -f $(clean_targets)
393 The modification time on the dependency file is adjusted to be
395 one second before the earliest time stamp of any other output
396 file. Consequently, it is suitable for use as the sentinel file
397 testifying to the fact the program was successfully run.
398 (-include is the GNU make way of specifying "include it if it
399 exists". Your make must support that feature or your bootstrap
400 process must create the file.)
401 All of this may also be specified using the DEPENDENCIES_OUTPUT
403 or AUTOGEN_MAKE_DEP environment variables. If defined, depen‐
404 dency information will be output. If defined with white space
405 free text that is something other than true, false, yes, no, 0
406 or 1, then the string is taken to be an output file name. If it
407 contains a string of white space characters, the first token is
408 as above and the second token is taken to be the target (sen‐
409 tinel) file as -MT in the paragraphs above. DEPENDENCIES_OUTPUT
410 will be ignored if there are multiple sequences of white space
411 characters or if its contents are, specifically, false, no or 0.
412 help, version and option handling
414 -?, --help
415 Display usage information and exit.
416 -!, --more-help
418 Pass the extended usage information through a pager.
419 -> [cfgfile], --save-opts[=cfgfile]
421 Save the option state to cfgfile. The default is the last con‐
422 figuration file listed in the OPTION PRESETS section, below.
423 The command will exit after updating the config file.
424 -< cfgfile, --load-opts=cfgfile, --no-load-opts
426 Load options from cfgfile. The no-load-opts form will disable
427 the loading of earlier config/rc/ini files. --no-load-opts is
428 handled early, out of order.
429 -v [{v|c|n}], --version[={v|c|n}]
431 Output version of program and exit. The default mode is `v', a
432 simple version. The `c' mode will print copyright information
433 and `n' will print the full copyright notice.
434
436 Any option that is not marked as not presettable may be preset by load‐
437 ing values from configuration ("RC" or ".INI") file(s) and values from
438 environment variables named:
439 AUTOGEN_<option-name> or AUTOGEN
440 The environmental presets take precedence (are processed later than)
441 the configuration files. The homerc files are "$HOME", and ".". If
442 any of these are directories, then the file .autogenrc is searched for
443 within those directories.
444
446 See OPTION PRESETS for configuration environment variables.
447
449 See OPTION PRESETS for configuration files.
450
452 Here is how the man page is produced:
453 autogen -Tagman-cmd.tpl -MFman-dep -MTstamp-man opts.def
454 This command produced this man page from the AutoGen option definition
456 file. It overrides the template specified in opts.def (normally
457 options.tpl) and uses agman-cmd.tpl. It also sets the make file depen‐
458 dency output to man-dep and the sentinel file (time stamp file) to
459 man-stamp. The base of the file name is derived from the defined
460 prog-name.
461 The texi invocation document is produced via:
463 autogen -Tagtexi-cmd.tpl -MFtexi-dep -MTtexi-stamp opts.def
464
466 One of the following exit values will be returned:
467 0 (EXIT_SUCCESS)
469 Successful program execution.
470 1 (EXIT_OPTION_ERROR)
472 The command options were misconfigured.
473 2 (EXIT_BAD_TEMPLATE)
475 An error was encountered processing the template.
476 3 (EXIT_BAD_DEFINITIONS)
478 The definitions could not be deciphered.
479 4 (EXIT_LOAD_ERROR)
481 An error was encountered during the load phase.
482 128 (EXIT_SIGNAL)
484 autogen exited due to catching a signal. If your template
485 includes string formatting, a number argument to a "%s" format‐
486 ting element will trigger a segmentation fault. Autogen will
487 catch the seg fault signal and exit with AUTOGEN_EXIT_SIGNAL(5).
488 Alternatively, AutoGen may have been interrupted with a kill(2)
489 signal. Subtract 128 from the actual exit code to detect the
490 signal number.
491 66 (EX_NOINPUT)
493 A specified configuration file could not be loaded.
494 70 (EX_SOFTWARE)
496 libopts had an internal operational error. Please report it to
497 autogen-users@lists.sourceforge.net. Thank you.
498
500 Bruce Korb
501
503 Copyright (C) 1992-2013 Bruce Korb all rights reserved. This program
504 is released under the terms of the GNU General Public License, version
505 3 or later.
506
508 Please send bug reports to: autogen-users@lists.sourceforge.net
509
511 This manual page was AutoGen-erated from the autogen option defini‐
512 tions.
513GNU AutoGen (5.18) 14 Jul 2013 autogen(1)