5. Invoking autogen

This chapter was generated by AutoGen, the aginfo template and the option descriptions for the autogen program. It documents the autogen usage text and option meanings.

This software is released under the GNU General Public License.

5.1 autogen usage help (-?)
5.5 base-name option (-b)
5.20 define option (-D)
5.6 definitions option
5.12 equate option
5.4 lib-template option (-l)
5.8 load-functions option (-F)
5.7 load-scheme option (-S)
5.14 loop-limit option
5.3 override-tpl option (-T)
5.10 select-suffix option (-o)
5.18 show-defs option
5.19 show-shell option
5.9 skip-suffix option (-s)
5.11 source-time option
5.2 templ-dirs option (-L)
5.15 timeout option (-t)
5.17 trace-out option
5.16 trace option
5.21 undefine option (-U)
5.13 writable option

5.1 autogen usage help (-?)

This is the automatically generated usage text for autogen:

@exampleindent 0

autogen - The Automated Program Generator - Ver. 5.3 USAGE: autogen [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ] Flg Arg Option-Name Description -L YES templ-dirs Template search directory list - may appear multiple times -T YES override-tpl Override template file - may not be preset -l YES lib-template Library template file - may appear multiple times -b YES base-name Base name for output file(s) - may not be preset YES definitions Definitions input file - disabled as --no-definitions - enabled by default - may not be preset -S YES load-scheme Scheme code file to load -F YES load-functions Load scheme callout library -s YES skip-suffix Omit the file with this suffix - may not be preset - may appear multiple times -o opt select-suffix specify this output suffix - may not be preset - may appear multiple times no source-time set mod times to latest source - disabled as --no-source-time YES equate characters considered equivalent no writable Allow output files to be writable - disabled as --not-writable - may not be preset The following options are often useful while debugging new templates: Flg Arg Option-Name Description Num loop-limit Limit on increment loops -t Num timeout Time limit for servers - must lie within the range: 0 to 3600 KWd trace tracing level of detail YES trace-out tracing output file or filter These options can be used to control what gets processed in the definitions files and template files. Flg Arg Option-Name Description -D YES define name to add to definition list - may appear multiple times -U YES undefine definition list removal pattern - an alternate for define Auto-supported Options: Flg Arg Option-Name Description -v opt version Output version information and exit -? no help Display usage information and exit -! no more-help Extended usage information passed thru pager -> opt save-opts Save the option state to an rc file -< YES load-opts Load options from an rc file - disabled as --no-load-opts - may appear multiple times Options may be specified by doubled hyphens and their name or by a single hyphen and the flag character (option value). AutoGen creates text files from templates using external definitions. The following option preset mechanisms are supported: - reading file $HOME/.autogenrc - reading file ./.autogenrc - examining environment variables named AUTOGEN_* The valid trace option keywords are: nothing templates block-macros expressions everything The definitions file (`<def-file>') can be specified with the `definitions' option or as the command argument, but not both. Omitting it or specifying `-' will result in reading definitions from standard input. The output file names are based on the template, but generally use the base name of the definition file. If standard in is read for the definitions, then `stdin' will be used for that base name. The suffixes to the base name are gotten from the template. However, the template file may specify the entire output file name. The generated files are always created in the current directory. If you need to place output in an alternate directory, `cd' to that directory and use the `--templ_dirs' option to search the original directory. `loop-limit' is used in debugging to stop runaway expansions.

@exampleindent 4

5.2 templ-dirs option (-L)

This is the "template search directory list" option.

This option has some usage constraints. It:

• may appear an unlimited number of times.

Add a directory to the list of directories to search when opening a template, either as the primary template or an included one. The last entry has the highest priority in the search list. That is to say, they are searched in reverse order.

5.3 override-tpl option (-T)

This is the "override template file" option.

This option has some usage constraints. It:

• may not be preset with environment variables or in initialization (rc) files.

Definition files specify the standard template that is to be expanded. This option will override that name and expand a different template.

5.4 lib-template option (-l)

This is the "library template file" option.

This option has some usage constraints. It:

• may appear an unlimited number of times.

DEFINE macros are saved from this template file for use in processing the main macro file. Template text aside from the DEFINE macros is is ignored.

5.5 base-name option (-b)

This is the "base name for output file(s)" option.

This option has some usage constraints. It:

• may not be preset with environment variables or in initialization (rc) files.

A template may specify the exact name of the output file. Normally, it does not. Instead, the name is composed of the base name of the definitions file with suffixes appended. This option will override the base name derived from the definitions file name. This is required if there is no definitions file and advisable if definitions are being read from stdin. If the definitions are being read from standard in, the base name defaults to `stdin'.

5.6 definitions option

This is the "definitions input file" option.

This option has some usage constraints. It:

• is enabled by default.
• may not be preset with environment variables or in initialization (rc) files.

Use this argument to specify the input definitions file with a command line option. If you do not specify this option, then there must be a command line argument that specifies the file, even if only to specify stdin with a hyphen (-). Specify, --no-definitions when you wish to process a template without any active AutoGen definitions.

5.7 load-scheme option (-S)

This is the "scheme code file to load" option. Use this option to pre-load Scheme scripts into the Guile interpreter before template processing begins. Please note that the AutoGen specific functions are not loaded until after argument processing. So, though they may be specified in lambda functions you define, they may not be invoked until after option processing is complete.

5.8 load-functions option (-F)

This is the "load scheme callout library" option. This option is used to load Guile-scheme callout functions. The automatically called initialization routine scm_init must be used to register these routines or data. This routine can be generated by using the following command and the `snarf.tpl' template. Read the introductory comment in `snarf.tpl' to see what the `getdefs(1AG)' comment must contain.

GRP_NAME=whateveryoulike eopt="subblock=exparg=arg_name,arg_desc,arg_optional,arg_list" eopt="$eopt defs=gfunc templ=snarf srcfile" eopt="assign=group=${GRP_NAME} assign=init=_init $eopt" eopt="$eopt autogen=${AG} base-name=expr" getdefs $eopt <<source-file-list>>

Note, however, that your functions must be named:

whateveryoulike_scm_<<function_name>>(...)

so you may wish to use a shorter group name.

5.9 skip-suffix option (-s)

This is the "omit the file with this suffix" option.

This option has some usage constraints. It:

• may appear an unlimited number of times.
• may not be preset with environment variables or in initialization (rc) files.

Occasionally, it may not be desirable to produce all of the output files specified in the template. (For example, only the `.h' header file, but not the `.c' program text.) To do this specify --skip-suffix=c on the command line.

5.10 select-suffix option (-o)

This is the "specify this output suffix" option.

This option has some usage constraints. It:

• may appear an unlimited number of times.
• may not be preset with environment variables or in initialization (rc) files.

If you wish to override the suffix specifications in the template, you can use one or more copies of this option. See the suffix specification in the 3.1 Format of the Pseudo Macro section of the info doc.

5.11 source-time option

This is the "set mod times to latest source" option. If you stamp your output files with the `DNE' macro output, then your output files will always be different, even if the content has not really changed. If you use this option, then the modification time of the output files will change only if the input files change. This will help reduce unneeded builds.

5.12 equate option

This is the "characters considered equivalent" option. This option will alter the list of characters considered equivalent. The default are the three characters, "_-^". (The latter is conventional on a Tandem, and I do a lot of work on the Tandem.)

5.13 writable option

This is the "allow output files to be writable" option.

This option has some usage constraints. It:

• may not be preset with environment variables or in initialization (rc) files.

This option will leave output files writable.Normally, output files are read-only.

5.14 loop-limit option

This is the "limit on increment loops" option. This option prevents runaway loops. For example, if you accidentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)", it will take a long time to finish. If you do have more than 256 entries in tables, you will need to specify a new limit with this option.

5.15 timeout option (-t)

This is the "time limit for servers" option.

This option has some usage constraints. It:

• must be compiled in by defining ENABLE_SHELL during the compilation.

AutoGen works with a shell server process. Most normal commands will complete in less than 10 seconds. If, however, your commands need more time than this, use this option.

The valid range is 0 to 3600 seconds (1 hour). Zero will disable the server time limit.

5.16 trace option

This is the "tracing level of detail" option. This option will cause AutoGen to display a trace of its template processing. There are five levels:

`nothing'

Does no tracing at all (default)

`templates'

Traces the invocation of DEFINEd macros and INCLUDEs

`block-macros'

Traces all block macros. The above, plus IF, FOR, CASE and WHILE.

`expressions'

Displays the results of expression evaluations

`everything'

Displays the invocation of every AutoGen macro, even TEXT macros.

5.17 trace-out option

This is the "tracing output file or filter" option. The output specified may be either a file name, or, if the option argument begins with the pipe operator (|), a command that will receive the tracing output as standard in. For example, --traceout='| less' will run the trace output through the less program.

5.18 show-defs option

This is the "show the definition tree" option.

This option has some usage constraints. It:

• must be compiled in by defining DEBUG during the compilation.
• may not be preset with environment variables or in initialization (rc) files.

This will print out the complete definition tree before processing the template.

5.19 show-shell option

This is the "show shell commands" option.

This option has some usage constraints. It:

• must be compiled in by defining DEBUG during the compilation.
• may not be preset with environment variables or in initialization (rc) files.

This will cause set -x to be executed in the shell, with the resultant output printed to /dev/tty. This option will have no effect if `--disable-shell' was specified at configure time.

5.20 define option (-D)

This is the "name to add to definition list" option.

This option has some usage constraints. It:

• may appear an unlimited number of times.
• is a member of the define class of options.

The AutoGen define names are used for the following purposes:

1. Sections of the AutoGen definitions may be enabled or disabled by using C-style #ifdef and #ifndef directives.
2. When defining a value for a name, you may specify the index for a particular value. That index may be a literal value, a define option or a value #define-d in the definitions themselves.
3. The name of a file may be prefixed with $NAME. That part of the name string will be replaced with the define-d value for NAME.
4. While processing a template, you may specify an index to retrieve a specific value. That index may also be a define-d value.

5.21 undefine option (-U)

This is the "definition list removal pattern" option.

This option has some usage constraints. It:

• may appear an unlimited number of times.
• may not be preset with environment variables or in initialization (rc) files.
• is a member of the define class of options.

Just like 'C', AutoGen uses #ifdef/#ifndef preprocessing directives. This option will cause the matching names to be removed from the list of defined values.