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