Go to the first, previous, next, last section, table of contents.

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.

autogen usage help (-?)

This is the automatically generated usage text for autogen:

@exampleindent 0

autogen - The Automated Program Generator - Ver. 5.2.11
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

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.

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.

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.

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'.

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.

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.

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.

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.

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 section Format of the Pseudo Macro section of the info doc.

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.

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.)

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.

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.

timeout option (-t)

This is the "time limit for servers" option. 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.

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.

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.

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.

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.

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.

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.

Go to the first, previous, next, last section, table of contents.