5. Invoking autogen

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.

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 (-?)

This is the automatically generated usage text for autogen:

@exampleindent 0

autogen - The Automated Program Generator - Ver. 5.5.5pre5
USAGE:  autogen [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ]
  Flg Arg Option-Name    Description
   -L Str templ-dirs     Template search directory list
                                - may appear multiple times
   -T Str override-tpl   Override template file
                                - may not be preset
   -l Str lib-template   Library template file
                                - may appear multiple times
   -b Str base-name      Base name for output file(s)
                                - may not be preset
      Str definitions    Definitions input file
                                - disabled as --no-definitions
                                - enabled by default
                                - may not be preset
   -S Str load-scheme    Scheme code file to load
   -F Str load-functions Load scheme callout library
   -s Str 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
      Str 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
                                  it must lie in one of the ranges:
                                  -1 exactly, or
                                  1 to 16777216
   -t Num timeout        Time limit for servers
                                  it must lie in the range: 0 to 3600
      KWd trace          tracing level of detail
      Str 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 Str define         name to add to definition list
                                - may appear multiple times
   -U Str 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
   -< Str load-opts      Load options from an rc file
                                - disabled as --no-load-opts
                                - may appear multiple times

Options are specified by doubled hyphens and their name
or by a single hyphen and the flag character.

AutoGen creates text files from templates using external definitions.

The following option preset mechanisms are supported:
 - reading file /dev/null
 - 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.

please send bug reports to:  autogen-bugs@lists.sf.net

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.

First, create a config file for getdefs, and then invoke getdefs loading that file:

cat > getdefs.cfg <<EOF
subblock    exparg=arg_name,arg_desc,arg_optional,arg_list
defs-to-get gfunc
template    snarf
srcfile
linenum
assign      group = name_of_some_group
assign      init  = _init
EOF

getdefs load=getdefs.cfg <<source-file-list>>

Note, however, that your functions must be named:

name_of_some_group_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 SHELL_ENABLED 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_ENABLED 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_ENABLED 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/. The $NAME part of the name string will be replaced with the define-d value for NAME.
4. When AutoGen is finished loading the definitions, the defined values are exported to the environment with, putenv(3). These values can then be used in shell scripts with ${NAME} references and in templates with (getenv "NAME").
5. 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.