autogen
(1)
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
User Commands AUTOGEN(1)
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
This manual page documents, briefly, the autogen command.
AutoGen is designed for generating program files that con-
tain 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 syn-
chronized.
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, rc/ini file processing, environment vari-
ables and so on.
All of this can be done mechanically; with the proper tem-
plates 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 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.
-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 different template.
(GNU AutoGen 5.9) Last change: 2014-06-17 1
User Commands AUTOGEN(1)
-l tpl-file, --lib-template=tpl-file
Library template file. This option 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.
-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. 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 defi-
nitions 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, @xref{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 vari-
ables 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 defi-
nitions.\n
-S file, --load-scheme=file
Scheme code file to load.
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.
(GNU AutoGen 5.9) Last change: 2014-06-17 2
User Commands AUTOGEN(1)
-F file, --load-functions=file
Load scheme function library.
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. This routine can be generated by using the fol-
lowing 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.
-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.
Occasionally, it may not be desirable to produce all of
the output files specified in the template. (For exam-
ple, only the .h header file, but not the .c program
text.) To do this specify --skip-suffix=c on the com-
mand line.
-o suffix, --select-suffix[=suffix]
specify this output suffix. This option may appear an
unlimited number of times. This option may not be pre-
set 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
(GNU AutoGen 5.9) Last change: 2014-06-17 3
User Commands AUTOGEN(1)
@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 differ-
ent, 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.
-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 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 virtual memory environment.
--equate=char-list
characters considered equivalent. The default char-
list for this option is:
_-^
This option will alter the list of characters consid-
ered equivalent. The default are the three characters,
"_-^". (The last is conventional on a Tandem/HP-Non-
Stop, 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 may not be
preset with environment variables or in initialization
(rc) files.
This option will leave output files writable. Nor-
mally, output files are read-only.
The following options are often useful while debugging new tem-
plates:
--loop-limit=lim
Limit on increment loops. This option takes an integer
number as its argument. The value of lim is con-
strained to being:
exactly -1, or
in the range 1 through 0x1000000
The default lim for this option is:
(GNU AutoGen 5.9) Last change: 2014-06-17 4
User Commands AUTOGEN(1)
256
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.
-t time-lim, --timeout=time-lim
Time limit for servers. This option takes an integer
number as its argument. The value of time-lim is con-
strained 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 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=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 server-shell templates
block-macros expressions everything
The default level for this option is:
nothing
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)
server-shell Traces all input and output to the server
shell. This includes a shell "independent" initializa-
tion script about 30 lines long. Its output is dis-
carded and not inserted into any template.
templates Traces the invocation of DEFINEd macros and
INCLUDEs
block-macros Traces all block macros. The above, plus
(GNU AutoGen 5.9) Last change: 2014-06-17 5
User Commands AUTOGEN(1)
IF, FOR, CASE and WHILE.
expressions Displays the results of expression evalua-
tions.
everything Displays the invocation of every AutoGen
macro, even TEXT macros (i.e. the text outside of macro
quotes).
--trace-out=file
tracing output file or filter.
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 stan-
dard in. For example, --traceout='| less' will run the
trace output through the less program.
--show-defs
Show the definition tree. This option may not be pre-
set with environment variables or in initialization
(rc) files.
This will print out the complete definition tree before
processing the template.
These options can be used to control what gets processed
in the definitions 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:
Sections of the AutoGen definitions may be enabled or
disabled by using C-style #ifdef and #ifndef direc-
tives.
When defining a value for a name, you may specify the
index for a particular value. That index may be a lit-
eral value, a define option or a value #define-d in the
definitions themselves.
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.
(GNU AutoGen 5.9) Last change: 2014-06-17 6
User Commands AUTOGEN(1)
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").
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 initial-
ization (rc) files.
Just like 'C', AutoGen uses #ifdef/#ifndef preprocess-
ing directives. This option will cause the matching
names to be removed from the list of defined values.
The following options are commonly used and are provided and
supported
by AutoOpts:"
-h, --short-help
Get short help text without an error exit. This option
may not be preset with environment variables or in ini-
tialization (rc) files.
This option specifies that the abbreviated usage text
should be emitted.
-?, --help
Display usage information and exit.
-!, --more-help
Extended usage information passed thru pager.
-> [rcfile], --save-opts[=rcfile]
Save the option state to rcfile. The default is the
last configuration 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
(GNU AutoGen 5.9) Last change: 2014-06-17 7
User Commands AUTOGEN(1)
copyright notice.
OPTION PRESETS
Any option that is not marked as not presettable may be pre-
set by loading 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.
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+-------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-------------------------+
|Availability | developer/build/autogen |
+---------------+-------------------------+
|Stability | Uncommitted |
+---------------+-------------------------+
SEE ALSO
This program is documented more fully in the AutoGen Info
system documentation.
EXAMPLES
autogen -T man.tpl --base-name=autogen 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 man.tpl. It also
overrides the base-name of the output file, which is nor-
mally derived from the input definition file name (viz.
opts).
AUTHOR
Bruce Korb
Please send bug reports to: [email protected]
forge.net
Released under the GNU General Public License.
This manual page was AutoGen-erated from the autogen option
definitions.
(GNU AutoGen 5.9) Last change: 2014-06-17 8
User Commands AUTOGEN(1)
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://ftp.gnu.org/gnu/autogen/rel5.9/autogen-5.9.tar.gz
Further information about this software can be found on the
open source community website at http://www.gnu.org/soft-
ware/autogen/.
(GNU AutoGen 5.9) Last change: 2014-06-17 9