|
|
i |
|
NAME
autogen - The Automated Program Generator
SYNOPSIS
autogen [-flag [value]]... [--opt-name [[=| ]value]]...[<def-file>]
AutoGen creates text files from templates using external definitions.
DESCRIPTION
AutoGen is designed for generating program files that contain repeti-
tive text with varied substitutions. The goal is to simplify the main-
tenance 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, con-
figuration file processing, environment variables and so on.
All of this can be done mechanically; with the proper templates and
this program.
OPTIONS
-L dir, --templ-dirs=dir
Template search directory list. This option may appear an
unlimited number of times.
Add a directory to the list of directories to search when open-
ing 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.
-T tpl-file, --override-tpl=tpl-file
Override template file. This option 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 dif-
ferent template.
-l tpl-file, --lib-template=tpl-file
Library template file. This option may appear an unlimited num-
ber of times.
DEFINE macros are saved from this template file for use in pro-
cessing the main macro file. Template text aside from the
DEFINE macros is is ignored.
-b name, --base-name=name
Base name for output file(s). This option may not be preset
with environment variables or in initialization (rc) files.
A template may specify the exact name of the output file. Nor-
mally, 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 def-
initions 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 specifica-
tion for the output suffix lists, see: pseudo macro.
--definitions=file, --no-definitions
Definitions input file. The no-definitions form will disable
the option. This option is enabled by default. This option 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.\n
-S file, --load-scheme=file
Scheme code file to load.
Use this option to pre-load Scheme scripts into the Guile inter-
preter 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 func-
tions you define, they may not be invoked until after option
processing is complete.
-F file, --load-functions=file
Load scheme function library.
This option is used to load Guile-scheme functions. The auto-
matically called initialization routine scm_init must be used to
register these routines or data.
-s suffix, --skip-suffix=suffix
Omit the file with this suffix. This option may appear an
unlimited number of times. This option may not be preset with
environment variables or in initialization (rc) files. This
option must not appear in combination with any of the following
options: select-suffix.
Occasionally, it may not be desirable to produce all of the out-
put 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.
-o suffix, --select-suffix[=suffix]
specify this output suffix. This option may appear an unlimited
number of times. This option may not be preset with environment
variables or in initialization (rc) files.
If you wish to override the suffix specifications in the tem-
plate, you can use one or more copies of this option. See the
suffix specification in the @ref{pseudo macro} section of the
info doc.
--source-time, --no-source-time
set mod times to latest source. The no-source-time form will
disable the 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 modi-
fication time of the output files will change only if the input
files change. This will help reduce unneeded builds.
-m, --no-fmemopen
Do not use in-mem streams.
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 prob-
lems if there is a shortage of virtual memory. If, for a par-
ticular 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.
--equate=char-list
characters considered equivalent. The default char-list for
this option is:
_-^
This option will alter the list of characters considered equiva-
lent. 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.)
--writable, --not-writable
Allow output files to be writable. The not-writable form will
disable the option.
This option will leave output files writable. Normally, output
files are read-only.
The following options are often useful while debugging new templates:
--loop-limit=lim
Limit on increment loops. This option takes an integer number
as its argument. The value of lim is constrained to being:
exactly -1, or
in the range 1 through 0x1000000
The default lim for this option is:
256
This option prevents runaway loops. For example, if you acci-
dentally 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.
--shell=shell
name or path name of shell to use.
By default, when AutoGen is built, the configuration is probed
for a reasonable Bourne-like shell to use for shell script pro-
cessing. 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/initializa-
tion file.
-t time-lim, --timeout=time-lim
Time limit for server shell. This option takes an integer num-
ber as its argument. The value of time-lim is constrained to
being:
in the range 0 through 3600
AutoGen works with a shell server process. Most normal commands
will complete in less than 10 seconds. If, however, your com-
mands need more time than this, use this option.
The valid range is 0 to 3600 seconds (1 hour). Zero will dis-
able the server time limit.
--trace=level
tracing level of detail. This option takes a keyword as its
argument. The argument sets an enumeration value that can be
tested by comparing them against the option value macro. The
available keywords are:
nothing debug-message server-shell
templates block-macros expressions
everything
or their numeric equivalent.
The default level for this option is:
nothing
This option will cause AutoGen to display a trace of its tem-
plate 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: DEBUG).
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). Addi-
tionally, if you rebuild the ``expr.ini'' file with debug-
ging enabled, then all calls to AutoGen defined scheme func-
tions 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.
--trace-out=file
tracing output file or filter.
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 (>>).
--show-defs
Show the definition tree. This option may not be preset with
environment variables or in initialization (rc) files.
This will print out the complete definition tree before process-
ing the template.
--used-defines
Show the definitions used. This option may not be preset with
environment variables or in initialization (rc) files.
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.
These options can be used to control what gets processed in the defini-
tions files and template files.
-D value, --define=value
name to add to definition list. This option may appear an
unlimited number of times.
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 defini-
tions 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.
-U name-pat, --undefine=name-pat
definition list removal pattern. This option may appear an
unlimited number of times. This option may not be preset with
environment variables or in initialization (rc) files.
Similar to 'C', AutoGen uses #ifdef/#ifndef preprocessing direc-
tives. This option will cause the matching names to be removed
from the list of defined values.
These options can be used to automate dependency tracking.
-M type, --make-dep[=type]
emit make dependency file. This option may appear an unlimited
number of times. This option may not be preset with environment
variables or in initialization (rc) files.
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 suc-
cessor dependencies (output target files). By default, the out-
put 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 depen-
dency 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 and T are meaningful and the latter has a some-
what different meaning: -MT<name> is interpreted as meaning
<name> is a sentinel file that will depend on all inputs (tem-
plates and definition files) and all the output files will
depend on this sentinel file. It is suitable for use as a real
make target.
This is the recommended usage:
-MFwhatever-you-like.dep -MTyour-sentinel-file
and then in your Makefile, make the autogen rule:
-include whatever-you-like.dep
your-sentinel-file:
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.
(-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, depen-
dency 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 (sen-
tinel) 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.
-C, --core
Leave a core dump on a failure exit.
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.
-?, --help
Display usage information and exit.
-!, --more-help
Pass the extended usage information through a pager.
-> [rcfile], --save-opts[=rcfile]
Save the option state to rcfile. The default is the last con-
figuration file listed in the OPTION PRESETS section, below.
-< rcfile, --load-opts=rcfile, --no-load-opts
Load options from rcfile. The no-load-opts form will disable
the loading of earlier RC/INI files. --no-load-opts is handled
early, out of order.
-v [{v|c|n}], --version[={v|c|n}]
Output version of program and exit. The default mode is `v', a
simple version. The `c' mode will print copyright information
and `n' will print the full copyright notice.
OPTION PRESETS
Any option that is not marked as not presettable may be preset by load-
ing values from configuration ("RC" or ".INI") file(s) and values from
environment variables named:
AUTOGEN_<option-name> or AUTOGEN
The environmental presets take precedence (are processed later than)
the configuration files. The homerc files are "$HOME", and ".". If
any of these are directories, then the file .autogenrc is searched for
within those directories.
ENVIRONMENT
See OPTION PRESETS for configuration environment variables.
FILES
See OPTION PRESETS for configuration files.
EXAMPLES
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 depen-
dency 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
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" format-
ting element will trigger a segmentation fault. Autogen will
catch the seg fault signal and exit with code 5.
AUTHORS
Bruce Korb
COPYRIGHT
Copyright (C) 1992-2011 Bruce Korb all rights reserved. This program
is released under the terms of the GNU General Public License, version
3 or later.
BUGS
Please send bug reports to: autogen-users@lists.sourceforge.net
NOTES
This manual page was AutoGen-erated from the autogen option defini-
tions.
GNU AutoGen (5.14) 28 Dec 2011 autogen(1)
This man page was converted to HTML by man2html
|
