| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AutoGen creates text files from templates using external definitions.
AutoGen is designed for generating program files that contain
repetitive text with varied substitutions. The goal is to simplify the
maintenance of programs that contain large amounts of repetitious text.
This is especially valuable if there are several blocks of such text
that must be kept synchronized.
One common example is the problem of maintaining the code required for processing program options. Processing options requires a minimum of four different constructs be kept in proper order in different places in your program. You need at least: The flag character in the flag string, code to process the flag when it is encountered, a global state variable or two, and a line in the usage text. You will need more things besides this if you choose to implement long option names, configuration file processing, environment variables and so on.
All of this can be done mechanically; with the proper templates and this program.
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, version 3 or later.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is the automatically generated usage text for autogen.
The text printed is the same whether selected with the help option
(‘--help’) or the more-help option (‘--more-help’). more-help will print
the usage text by passing it through a pager program.
more-help is disabled on platforms without a working
fork(2) function. The PAGER environment variable is
used to select the program, defaulting to ‘more’. Both will exit
with a status code of 0.
autogen (GNU AutoGen) - The Automated Program Generator - Ver. 5.18.6pre12
Usage: autogen [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ]
The following options select definitions, templates and scheme functions
to use:
Flg Arg Option-Name Description
-L Str templ-dirs Search for templates in DIR
- may appear multiple times
-T Str override-tpl Use TPL-FILE for the template
- may not be preset
Str definitions Read definitions from FILE
- disabled as '--no-definitions'
- enabled by default
- may not be preset
Str shell name or path name of shell to use
-m no no-fmemopen Do not use in-mem streams
Str equate characters considered equivalent
The following options modify how output is handled:
Flg Arg Option-Name Description
-b Str base-name Specify NAME as the base name for output
- may not be preset
no source-time set mod times to latest source
- disabled as '--no-source-time'
no writable Allow output files to be writable
- disabled as '--not-writable'
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
-t Num timeout Limit server shell operations to SECONDS
- it must be in the range:
0 to 3600
KWd trace tracing level of detail
Str trace-out tracing output file or filter
no show-defs Show the definition tree
- may not be preset
no used-defines Show the definitions used
- may not be preset
-C no core Leave a core dump on a failure exit
These options can be used to control what gets processed in the
definitions files and template files:
Flg Arg Option-Name Description
-s Str skip-suffix Skip the file with this SUFFIX
- prohibits the option 'select-suffix'
- may not be preset
- may appear multiple times
-o Str select-suffix specify this output suffix
- may not be preset
- may appear multiple times
-D Str define name to add to definition list
- may appear multiple times
-U Str undefine definition list removal pattern
- an alternate for 'define'
This option is 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
help, version and option handling:
Flg Arg Option-Name Description
-R Str reset-option reset an option's state
-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.
Packaged by Bruce (2015-08-08)
Report autogen bugs to bkorb@gnu.org
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following options select definitions, templates and scheme functions to use.
This is the “search for templates in ‘dir’” option. This option takes a string argument ‘DIR’.
This option has some usage constraints. It:
Add a directory to the list of directories autogen searches 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.
This is the “use ‘tpl-file’ for the template” option. This option takes a string argument ‘TPL-FILE’.
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.
This is the “load autogen macros from ‘tpl-file’” option. This option takes a string argument ‘TPL-FILE’.
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.
Do not use this. Instead, use the INCLUDE macro in your template.
NOTE: THIS OPTION IS DEPRECATED
This is the “read definitions from ‘file’” option. This option takes a string argument ‘FILE’.
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.
This is the “name or path name of shell to use” option. This option takes a string argument ‘shell’.
This option has some usage constraints. It:
SHELL_ENABLED during the compilation.
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.
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.
This is the “characters considered equivalent” option. This option takes a string argument ‘char-list’. 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] | [ ? ] |
The following options modify how output is handled.
This is the “specify name as the base name for output” option.
This option takes a string argument ‘NAME’.
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.
This is the “set mod times to latest source” option.
This option has some usage constraints. It:
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.
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] | [ ? ] |
The following options are often useful while debugging new templates. They specify limits that prevent the template from taking overly long or producing more output than expected.
This is the “limit on increment loops” option. This option takes a number argument ‘lim’. 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.
This is the “limit server shell operations to seconds” option.
This option takes a number argument ‘SECONDS’.
This option has some usage constraints. It:
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.
This is the “tracing level of detail” option. This option takes a keyword argument ‘level’.
This option has some usage constraints. It:
nothing debug-message server-shell
templates block-macros expressions
everything
|
or their numeric equivalent.
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:
Does no tracing at all (default)
Print messages from the "DEBUG" AutoGen macro (see section DEBUG - Print debug message to trace output).
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.
Traces the invocation of DEFINEd macros and INCLUDEs
Traces all block macros. The above, plus IF, FOR,
CASE and WHILE.
Displays the results of expression evaluations.
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.
This is the “tracing output file or filter” option.
This option takes a string argument ‘file’.
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
preceding the file name with two greater-than characters (>>).
This is the “show the definition tree” option.
This option has some usage constraints. It:
DEBUG_ENABLED during the compilation.
This will print out the complete definition tree before processing the template.
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.
This is the “leave a core dump on a failure exit” option.
This option has some usage constraints. It:
HAVE_SYS_RESOURCE_H during the compilation.
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] | [ ? ] |
These options can be used to control what gets processed in the definitions files and template files. They specify which outputs and parts of outputs to produce.
This is the “skip the file with this ‘suffix’” option. This option takes a string argument ‘SUFFIX’.
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.
This is the “specify this output suffix” option. This option takes a string argument ‘SUFFIX’.
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.
This is the “name to add to definition list” option. This option takes a string argument ‘value’.
This option has some usage constraints. It:
The AutoGen define names are used for the following purposes:
$NAME/.
The $NAME part of the name string will be replaced with
the define-d value for NAME.
putenv(3).
These values can then be used in shell scripts with ${NAME}
references and in templates with (getenv "NAME").
It is entirely equivalent to place this name in the exported environment. Internally, that is what AutoGen actually does with this option.
This is the “definition list removal pattern” option. This option takes a string argument ‘name-pat’.
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] | [ ? ] |
This option is used to automate dependency tracking.
This is the “emit make dependency file” option. This option takes an optional string argument ‘type’.
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 just
emitting the predecessor dependencies, this also emits the successor
dependencies (output target 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 start time.
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.
However, only F, Q, T and P are meaningful. All but F have somewhat
different meanings. -MT<name> 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. It is suitable for use as a real make target.
Q is treated identically to T, except dollar characters (’$’) are
doubled. P causes a special clean (clobber) phoney rule to be inserted
into the make file fragment. An empty rule is always created for
building the list of targets.
This is the recommended usage:
-MFwhatever-you-like.dep -MTyour-sentinel-file -MP |
and then in your Makefile, make the ‘autogen’ rule:
-include whatever-you-like.dep
clean_targets += clean-your-sentinel-file
your-sentinel-file:
autogen -MT$@ -MF$*.d .....
local-clean :
rm -f $(clean_targets)
|
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. (-include is
the GNU make way of specifying "include it if it exists". Your make
must support that feature or your bootstrap process must create the
file.)
All of this may also be specified using the DEPENDENCIES_OUTPUT
or AUTOGEN_MAKE_DEP environment variables. If defined,
dependency information will be output. If defined with white space
free text that is something other than true, false,
yes, no, 0 or 1, then the string is taken
to be an output file name. If it contains a string of white space
characters, the first token is as above and the second token is taken
to be the target (sentinel) file as -MT in the paragraphs
above. DEPENDENCIES_OUTPUT will be ignored if there are
multiple sequences of white space characters or if its contents are,
specifically, false, no or 0.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 styles within one configuration file.
Compound values and carefully constructed string values may also be specified using XML syntax:
<option-name> <sub-opt>...<...>...</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).
The command line options relating to configuration and/or usage help are:
Print the program version to standard out, optionally with licensing information, then exit 0. The optional argument specifies how much licensing detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the first letter of the argument is examined:
Only print the version. This is the default.
Name the copyright usage licensing terms.
Print the full copyright usage licensing terms.
Print abbreviated usage to standard out, then exit 0.
Resets the specified option to the compiled-in initial state. This will undo anything that may have been set by configuration files. The option argument may be either the option flag character or its long name.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
One of the following exit values will be returned:
Successful program execution.
The command options were misconfigured.
An error was encountered processing the template.
The definitions could not be deciphered.
An error was encountered during the load phase.
a file system error stopped the program.
Insufficient memory to operate.
autogen 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 AUTOGEN_EXIT_SIGNAL(5). Alternatively, AutoGen
may have been interrupted with a kill(2) signal.
Subtract 128 from the actual exit code to detect the signal number.
A specified configuration file could not be loaded.
libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is how the man page is produced:
autogen -Tagman-cmd.tpl -MFman-dep -MTstamp-man opts.def |
This command produced this man page from the AutoGen option definition
file. It overrides the template specified in ‘opts.def’ (normally
‘options.tpl’) and uses ‘agman-cmd.tpl’. It also sets the
make file dependency output to ‘man-dep’ and the sentinel file
(time stamp file) to ‘man-stamp’. The base of the file name is
derived from the defined prog-name.
The texi invocation document is produced via:
autogen -Tagtexi-cmd.tpl -MFtexi-dep -MTtexi-stamp opts.def |
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.