[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Invoking autogen

AutoGen creates text files from templates using external definitions. AutoGen is a tool designed for generating program files that contain repetitive text with varied substitutions.

The definitions (<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.

This chapter was generated by AutoGen, using the agtexi-cmd template and the option descriptions for the autogen program.

This software is released under the GNU General Public License.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 autogen usage help (-?)

This is the automatically generated usage text for autogen:

 
autogen (GNU AutoGen) - The Automated Program Generator - Ver. 5.12
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 function library
   -s Str skip-suffix    Omit the file with this suffix
                                - prohibits these options:
                                select-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
   -m no  no-fmemopen    Do not use in-mem streams
      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
                                - is scalable with a suffix: k/K/m/M/g/G/t/T
                                - It must lie in one of the ranges:
                                  -1 exactly, or
                                  1 to 16777216
      Str shell          name or path name of shell to use
   -t Num timeout        Time limit for server shell
                                - It must be in the range:
                                  0 to 3600
      KWd trace          tracing level of detail
      Str trace-out      tracing output file or filter
      --- show-defs      This option has been disabled
      no  used-defines   Show the definitions used
                                - may not be preset

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

These options can be used to automate dependency tracking.

  Flg Arg Option-Name    Description
   -M opt make-dep       emit make dependency file
                                - may not be preset
                                - may appear multiple times
   -C no  core           Leave a core dump on a failure exit

version and help options:

  Flg Arg Option-Name    Description
   -v opt version        Output version information and exit
   -? no  help           Display extended usage information and exit
   -! no  more-help      Extended usage information passed thru pager
   -u no  usage          Abbreviated usage to stdout
   -> opt save-opts      Save the option state to a config file
   -< Str load-opts      Load options from a config 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 $HOME
 - reading file ./.autogenrc
 - examining environment variables named AUTOGEN_*

The valid "trace" option keywords are:
  nothing       debug-message server-shell  templates     block-macros
  expressions   everything
  or an integer from 0 through 6

AutoGen is a tool designed for generating program files that contain
repetitive text with varied substitutions.

please send bug reports to:  autogen-users@lists.sourceforge.net

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 base-name option (-b)

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

This option has some usage constraints. It:

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’. Any leading directory components in the name will be silently removed. If you wish the output file to appear in a particular directory, it is recommended that you "cd" into that directory first, or use directory names in the format specification for the output suffix lists, See section Format of the Pseudo Macro.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 core option (-C)

This is the “leave a core dump on a failure exit” option.

This option has some usage constraints. It:

Many systems default to a zero sized core limit. If the system has the sys/resource.h header and if this option is supplied, then in the failure exit path, autogen will attempt to set the soft core limit to whatever the hard core limit is. If that does not work, then an administrator must raise the hard core size limit.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 define option (-D)

This is the “name to add to definition list” option.

This option has some usage constraints. It:

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 definitions option

This is the “definitions input file” option.

This option has some usage constraints. It:

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.\n


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6 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 last is conventional on a Tandem/HP-NonStop, and I used to do a lot of work on Tandems.)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.7 lib-template option (-l)

This is the “library template file” option.

This option has some usage constraints. It:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.8 load-functions option (-F)

This is the “load scheme function library” option.

This option has some usage constraints. It:

This option is used to load Guile-scheme functions. The automatically called initialization routine scm_init must be used to register these routines or data.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.11 make-dep option (-M)

This is the “emit make dependency file” option.

This option has some usage constraints. It:

This option behaves fairly closely to the way the -M series of options work with the gcc compiler, except that instead of emitting the predecessor dependencies, this emits both the predecessor and the successor dependencies (output files). By default, the output dependency information will be placed in <base-name>.d, but may also be specified with -MF<file>. The time stamp on this file will be manipulated so that it will be one second older than the oldest primary output file.

The target in this dependency file will normally be the dependency file name, but may also be overridden with -MT<targ-name>. AutoGen will not alter the contents of that file, but it may create it and it will adjust the modification time to match the dependency file.

NB: these second letters are part of the option argument, so -MF <file> must have the space character quoted or omitted, and -M "F <file>" is acceptable because the F is part of the option argument.

-M may be followed by any of the letters M, F, P, T, Q, D, or G. They are not all meaningful and one has a somewhat different meaning: -MT<name> This is interpreted as meaning <name> is a sentinel file that will depend on all inputs (templates and definition files) and all the output files will depend on this sentinel file.

This is the recommended usage:

 
-MFwhatever-you-like.dep -MTyour-sentinel-file

and then in your Makefile, make the ‘autogen’ rule:

 
whatever-you-like.dep:
    autogen -MT$@ -MF$*.d .....

The modification time on the dependency file is adjusted to be one second before the earliest time stamp of any other output file. Consequently, it is suitable for use as the sentinel file testifying to the fact the program was successfully run.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.12 no-fmemopen option (-m)

This is the “do not use in-mem streams” option. If the local C library supports "fopencookie(3GNU)", or "funopen(3BSD)" then AutoGen prefers to use in-memory stream buffer opens instead of anonymous files. This may lead to problems if there is a shortage of virtual memory. If, for a particular application, you run out of memory, then specify this option. This is unlikely in a modern 64-bit virtual memory environment.

On platforms without these functions, the option is accepted but ignored. fmemopen(POSIX) is not adequate because its string buffer is not reallocatable. open_memstream(POSIX) is also not adequate because the stream is only opened for output. AutoGen needs a reallocatable buffer available for both reading and writing.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.13 override-tpl option (-T)

This is the “override template file” option.

This option has some usage constraints. It:

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.14 select-suffix option (-o)

This is the “specify this output suffix” option.

This option has some usage constraints. It:

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.15 shell option

This is the “name or path name of shell to use” option.

This option has some usage constraints. It:

By default, when AutoGen is built, the configuration is probed for a reasonable Bourne-like shell to use for shell script processing. If a particular template needs an alternate shell, it must be specified with this option on the command line, with an environment variable (SHELL) or in the configuration/initialization file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.16 show-defs option

This is the “show the definition tree” option.

This option has some usage constraints. It:

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.17 skip-suffix option (-s)

This is the “omit the file with this suffix” option.

This option has some usage constraints. It:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.19 templ-dirs option (-L)

This is the “template search directory list” option.

This option has some usage constraints. It:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.20 timeout option (-t)

This is the “time limit for server shell” option.

This option has some usage constraints. It:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.21 trace option

This is the “tracing level of detail” option.

This option has some usage constraints. It:

This option will cause AutoGen to display a trace of its template processing. There are six levels, each level including messages from the previous levels:

nothing

Does no tracing at all (default)

debug-message

Print messages from the "DEBUG" AutoGen macro (see section DEBUG - Print debug message to trace output).

server-shell

Traces all input and output to the server shell. This includes a shell "independent" initialization script about 30 lines long. Its output is discarded and not inserted into any template.

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 (i.e. the text outside of macro quotes). Additionally, if you rebuild the “expr.ini” file with debugging enabled, then all calls to AutoGen defined scheme functions will also get logged:

 
cd ${top_builddir}/agen5
DEBUG_ENABLED=true bash bootstrap.dir expr.ini
make CFLAGS='-g -DDEBUG_ENABLED=1'

Be aware that you cannot rebuild this source in this way without first having installed the autogen executable in your search path. Because of this, "expr.ini" is in the distributed source list, and not in the dependencies.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.22 trace-out option

This is the “tracing output file or filter” option. The output specified may be a file name, a file that is appended to, 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. Appending to a file is specified by preceeding the file name with two greater-than characters (>>).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.23 undefine option (-U)

This is the “definition list removal pattern” option.

This option has some usage constraints. It:

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.24 used-defines option

This is the “show the definitions used” option.

This option has some usage constraints. It:

This will print out the names of definition values searched for during the processing of the template, whether actually found or not. There may be other referenced definitions in a template in portions of the template not evaluated. Some of the names listed may be computed names and others AutoGen macro arguments. This is not a means for producing a definitive, all-encompassing list of all and only the values used from a definition file. This is intended as an aid to template documentation only.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.25 writable option

This is the “allow output files to be writable” option.

This option has some usage constraints. It:

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.26 presetting/configuring autogen

Any option that is not marked as not presettable may be preset by loading values from configuration ("rc" or "ini") files, and values from environment variables named AUTOGEN and AUTOGEN_<OPTION_NAME>. “<OPTION_NAME>” must be one of the options listed above in upper case and segmented with underscores. The AUTOGEN variable will be tokenized and parsed like the command line. The remaining variables are tested for existence and their values are treated like option arguments.

libopts will search in 2 places for configuration files:

The environment variables HOME, and PWD are expanded and replaced when ‘autogen’ runs. For any of these that are plain files, they are simply processed. For any that are directories, then a file named ‘.autogenrc’ is searched for within that directory and processed.

Configuration files may be in a wide variety of formats. The basic format is an option name followed by a value (argument) on the same line. Values may be separated from the option name with a colon, equal sign or simply white space. Values may be continued across multiple lines by escaping the newline with a backslash.

Multiple programs may also share the same initialization file. Common options are collected at the top, followed by program specific segments. The segments are separated by lines like:

 
[AUTOGEN]

or by

 
<?program autogen>

Do not mix these within one configuration file.

Compound values and carefully constructed string values may also be specified using XML syntax:

 
<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>

yielding an option-name.sub-opt string value of

 
"...<...>..."

AutoOpts does not track suboptions. You simply note that it is a hierarchicly valued option. AutoOpts does provide a means for searching the associated name/value pair list (see: optionFindValue).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.27 autogen exit status

One of the following exit values will be returned:

0

Successful program execution.

1

The command options were misconfigured.

2

An error was encountered processing the template.

3

The definitions could not be deciphered.

4

An error was encountered during the load phase.

5

Program exited due to catching a signal. If your template includes string formatting, a number argument to a "%s" formatting element will trigger a segmentation fault. Autogen will catch the seg fault signal and exit with code 5.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.28 autogen Description


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.29 autogen Examples


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on February 26, 2016 using texi2html 1.82.