path: root/agen5/autogen.1

.TH autogen 1 "11 Aug 2012" "GNU AutoGen (5.16.2)" "User Commands"
.\"
.\"  DO NOT EDIT THIS FILE   (opts.man)
.\"  
.\"  It has been AutoGen-ed  August 11, 2012 at 09:41:44 AM by AutoGen 5.16.2pre7
.\"  From the definitions    /old-home/bkorb/ag/ag/agen5/opts.def
.\"  and the template file   agman-cmd
.\"
.SH NAME
autogen \- The Automated Program Generator
.SH SYNOPSIS
.B autogen
.\" Mixture of short (flag) options and long options
.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ <def-file> ]
.PP
AutoGen creates text files from templates using external definitions.
.SH DESCRIPTION
\fBAutoGen\fP 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.
.sp
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.
.sp
All of this can be done mechanically; with the proper templates
and this program.
.SH "OPTIONS"
.SS "The following options select definitions, templates and scheme functions to use"
.TP
.BR \-L " \fIdir\fP, " \-\-templ\-dirs "=" \fIdir\fP
Template search directory list.
This option may appear an unlimited number of times.
.sp
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.
.TP
.BR \-T " \fItpl\-file\fP, " \-\-override\-tpl "=" \fItpl\-file\fP
Override template file.
This option may not be preset with environment variables
or in initialization (rc) files.
.sp
Definition files specify the standard template that is to be expanded.
This option will override that name and expand a different template.
.TP
.BR \-l " \fItpl\-file\fP, " \-\-lib\-template "=" \fItpl\-file\fP
Library template file.
This option may appear an unlimited number of times.
.sp
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.
.TP
.BR \-\-definitions "=\fIfile\fP", " \fB\-\-no\-definitions\fP"
Definitions input file.
The \fIno\-definitions\fP 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.
.sp
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 (\fB\-\fP).
Specify, \fB\-\-no\-definitions\fP when you wish to process
a template without any active AutoGen definitions.
.TP
.BR \-S " \fIfile\fP, " \-\-load\-scheme "=" \fIfile\fP
Scheme code file to load.
.sp
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.
.TP
.BR \-F " \fIfile\fP, " \-\-load\-functions "=" \fIfile\fP
Load scheme function library.
.sp
This option is used to load Guile\-scheme functions.  The automatically
called initialization routine \fBscm_init\fP must be used to register
these routines or data.
.TP
.BR \-\-shell "=\fIshell\fP"
name or path name of shell to use.
.sp
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
(\fBSHELL\fP) or in the configuration/initialization file.
.TP
.BR \-m ", " \-\-no\-fmemopen
Do not use in\-mem streams.
.sp
If the local C library supports "\fBfopencookie(3GNU)\fP", or
"\fBfunopen(3BSD)\fP" 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.
.sp
On platforms without these functions, the option is accepted
but ignored.  \fBfmemopen(POSIX)\fP is not adequate because
its string buffer is not reallocatable.  \fBopen_memstream(POSIX)\fP
is \fIalso\fP not adequate because the stream is only opened for
output.  AutoGen needs a reallocatable buffer available for both
reading and writing.
.TP
.BR \-\-equate "=\fIchar\-list\fP"
characters considered equivalent.
The default \fIchar\-list\fP for this option is:
.ti +4
 _\-^
.sp
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.)
.SS "The following options modify how output is handled"
.TP
.BR \-b " \fIname\fP, " \-\-base\-name "=" \fIname\fP
Base name for output file(s).
This option may not be preset with environment variables
or in initialization (rc) files.
.sp
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 \fIstdin\fP.  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: pseudo macro.
.TP
.BR \-\-source\-time, " \fB\-\-no\-source\-time\fP"
set mod times to latest source.
The \fIno\-source\-time\fP form will disable the option.
.sp
If you stamp your output files with the \fBDNE\fP 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.
.TP
.BR \-\-writable, " \fB\-\-not\-writable\fP"
Allow output files to be writable.
The \fInot\-writable\fP form will disable the option.
.sp
This option will leave output files writable.
Normally, output files are read\-only.
.SS "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.
.sp
.TP
.BR \-\-loop\-limit "=\fIlim\fP"
Limit on increment loops.
This option takes an integer number as its argument.
The value of \fIlim\fP is constrained to being:
.in +4
.nf
.na
exactly \-1, or
in the range  1 through 0x1000000
.fi
.in -4
The default \fIlim\fP for this option is:
.ti +4
 256
.sp
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.
.TP
.BR \-t " \fItime\-lim\fP, " \-\-timeout "=" \fItime\-lim\fP
Time limit for server shell.
This option takes an integer number as its argument.
The value of \fItime\-lim\fP is constrained to being:
.in +4
.nf
.na
in the range  0 through 3600
.fi
.in -4
.sp
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.
.sp
The valid range is 0 to 3600 seconds (1 hour).
Zero will disable the server time limit.
.TP
.BR \-\-trace "=\fIlevel\fP"
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:
.in +4
.nf
.na
nothing       debug\-message server\-shell
templates     block\-macros  expressions
everything
.fi
or their numeric equivalent.
.in -4
.sp
The default \fIlevel\fP for this option is:
.ti +4
 nothing
.sp
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:
.sp
.sp
.IR "nothing"
Does no tracing at all (default)
.sp
.sp
.IR "debug\-message"
Print messages from the "DEBUG" AutoGen macro (see: DEBUG).
.sp
.sp
.IR "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.
.sp
.sp
.IR "templates"
Traces the invocation of \fBDEFINE\fPd macros and \fBINCLUDE\fPs
.sp
.sp
.IR "block\-macros"
Traces all block macros.  The above, plus \fBIF\fP, \fBFOR\fP,
\fBCASE\fP and \fBWHILE\fP.
.sp
.sp
.IR "expressions"
Displays the results of expression evaluations.
.sp
.sp
.IR "everything"
Displays the invocation of every AutoGen macro, even \fBTEXT\fP 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:
.br
.nf
    cd ${top_builddir}/agen5
    DEBUG_ENABLED=true bash bootstrap.dir expr.ini
    make CFLAGS='\-g \-DDEBUG_ENABLED=1'
.fi
.sp
Be aware that you cannot rebuild this source in this way without first
having installed the \fBautogen\fP executable in your search path.
Because of this, "expr.ini" is in the distributed source list, and
not in the dependencies.
.br
.TP
.BR \-\-trace\-out "=\fIfile\fP"
tracing output file or filter.
.sp
The output specified may be a file name, a file that is appended to,
or, if the option argument begins with the \fBpipe\fP operator
(\fB|\fP), a command that will receive the tracing output as standard
in.  For example, \fB\-\-traceout='| less'\fP will run the trace output
through the \fBless\fP program.  Appending to a file is specified by
preceeding the file name with two greater\-than characters (\fB>>\fP).
.TP
.BR \-\-show\-defs
Show the definition tree.
This option may not be preset with environment variables
or in initialization (rc) files.
.sp
This will print out the complete definition tree before processing
the template.
.TP
.BR \-\-used\-defines
Show the definitions used.
This option may not be preset with environment variables
or in initialization (rc) files.
.sp
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.
.TP
.BR \-C ", " \-\-core
Leave a core dump on a failure exit.
.sp
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.
.SS "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.
.sp
.TP
.BR \-s " \fIsuffix\fP, " \-\-skip\-suffix "=" \fIsuffix\fP
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.
.sp
Occasionally, it may not be desirable to produce all of the output
files specified in the template.  (For example, only the \fI.h\fP
header file, but not the \fI.c\fP program text.)  To do this
specify \fB\-\-skip\-suffix=c\fP on the command line.
.TP
.BR \-o " \fIsuffix\fP, " \-\-select\-suffix "=" \fIsuffix\fP
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.
.sp
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 @ref{pseudo macro} section of the info doc.
.TP
.BR \-D " \fIvalue\fP, " \-\-define "=" \fIvalue\fP
name to add to definition list.
This option may appear an unlimited number of times.
.sp
The AutoGen define names are used for the following purposes:
.sp
.sp 1
Sections of the AutoGen definitions may be enabled or disabled
by using C\-style #ifdef and #ifndef directives.
.sp 1
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.
.sp 1
The name of a file may be prefixed with \fB$NAME/\fP.
The \fB$NAME\fP part of the name string will be replaced with
the define\-d value for \fBNAME\fP.
.sp 1
When AutoGen is finished loading the definitions, the defined values
are exported to the environment with, \fBputenv(3)\fP.
These values can then be used in shell scripts with \fB${NAME@\fP}
references and in templates with \fB(getenv "NAME")\fP.
.sp 1
While processing a template, you may specify an index to retrieve
a specific value.  That index may also be a define\-d value.
.br
.sp
It is entirely equivalent to place this name in the exported environment.
Internally, that is what AutoGen actually does with this option.
.TP
.BR \-U " \fIname\-pat\fP, " \-\-undefine "=" \fIname\-pat\fP
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.
.sp
Similar to 'C', AutoGen uses \fB#ifdef/#ifndef\fP preprocessing
directives.  This option will cause the matching names to be
removed from the list of defined values.
.SS "This option is used to automate dependency tracking"
.TP
.BR \-M " \fItype\fP, " \-\-make\-dep [ =\fItype\fP ]
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.
.sp
.sp
This option behaves fairly closely to the way the \fB\-M\fP 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 \fB<base\-name>.d\fP, but may also be
specified with \fB\-MF<file>\fP.  The time stamp on this file will be
manipulated so that it will be one second older than the oldest
primary output file.
.sp
The target in this dependency file will normally be the dependency
file name, but may also be overridden with \fB\-MT<targ\-name>\fP.
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.
.sp
\fBNB:\fP these second letters are part of the option argument, so
\fB\-MF <file>\fP must have the space character quoted or omitted, and
\fB\-M "F <file>"\fP is acceptable because the \fBF\fP is part of the
option argument.
.sp
\fB\-M\fP 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.  \fB\-MT<name>\fP is interpreted as meaning
\fB<name>\fP 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.
.sp
This is the recommended usage:
.nf
      \-MFwhatever\-you\-like.dep \-MTyour\-sentinel\-file \-MP
.fi
and then in your \fBMakefile\fP, make the \fIautogen\fP rule:
.nf
      \-include whatever\-you\-like.dep
      clean_targets += clean\-your\-sentinel\-file
      your\-sentinel\-file:
          autogen \-MT$@ \-MF$*.d .....
      local\-clean :
          rm \-f $(clean_targets)
.fi
.sp
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.  (\fB\-include\fP 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.)
.sp
All of this may also be specified using the \fBDEPENDENCIES_OUTPUT\fP
or \fBAUTOGEN_MAKE_DEP\fP environment variables.  If defined,
dependency information will be output.  If defined with white space
free text that is something other than \fBtrue\fP, \fBfalse\fP,
\fByes\fP, \fBno\fP, \fB0\fP or \fB1\fP, 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 \fB\-MT\fP in the paragraphs
above.  \fBDEPENDENCIES_OUTPUT\fP will be ignored if there are
multiple sequences of white space characters or if its contents are,
specifically, \fBfalse\fP, \fBno\fP or \fB0\fP.
.TP
.BR \-? , " \-\-help"
Display usage information and exit.
.TP
.BR \-! , " \-\-more\-help"
Pass the extended usage information through a pager.
.TP
.BR \-> " [\fIrcfile\fP]," " \-\-save\-opts" "[=\fIrcfile\fP]"
Save the option state to \fIrcfile\fP.  The default is the \fIlast\fP
configuration file listed in the \fBOPTION PRESETS\fP section, below.
.TP
.BR \-< " \fIrcfile\fP," " \-\-load\-opts" "=\fIrcfile\fP," " \-\-no\-load\-opts"
Load options from \fIrcfile\fP.
The \fIno\-load\-opts\fP form will disable the loading
of earlier RC/INI files.  \fI\-\-no\-load\-opts\fP is handled early,
out of order.
.TP
.BR \-v " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]"
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.
.sp
.SH "OPTION PRESETS"
Any option that is not marked as \fInot presettable\fP may be preset
by loading values from configuration ("RC" or ".INI") file(s) and values from
environment variables named:
.nf
  \fBAUTOGEN_<option-name>\fP or \fBAUTOGEN\fP
.fi
.ad
The environmental presets take precedence (are processed later than)
the configuration files.
The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
If any of these are directories, then the file \fI.autogenrc\fP
is searched for within those directories.
.SH "ENVIRONMENT"
See \fBOPTION PRESETS\fP for configuration environment variables.
.SH "FILES"
See \fBOPTION PRESETS\fP for configuration files.
.SH EXAMPLES
Here is how the man page is produced:
.br
.in +4
.nf
autogen \-Tagman\-cmd.tpl \-MFman\-dep \-MTstamp\-man opts.def
.in -4
.fi
.sp
This command produced this man page from the AutoGen option definition
file.  It overrides the template specified in \fIopts.def\fP (normally
\fIoptions.tpl\fP) and uses \fIagman\-cmd.tpl\fP.  It also sets the
make file dependency output to \fIman\-dep\fP and the sentinel file
(time stamp file) to \fIman\-stamp\fP.  The base of the file name is
derived from the defined \fBprog\-name\fP.
.sp
The texi invocation document is produced via:
.br
.in +4
.nf
autogen \-Tagtexi\-cmd.tpl \-MFtexi\-dep \-MTtexi\-stamp opts.def
.in -4
.fi
.SH "EXIT STATUS"
One of the following exit values will be returned:
.TP
.BR 0 " (EXIT_SUCCESS)"
Successful program execution.
.TP
.BR 1 " (EXIT_OPTION_ERROR)"
The command options were misconfigured.
.TP
.BR 2 " (EXIT_BAD_TEMPLATE)"
An error was encountered processing the template.
.TP
.BR 3 " (EXIT_BAD_DEFINITIONS)"
The definitions could not be deciphered.
.TP
.BR 4 " (EXIT_LOAD_ERROR)"
An error was encountered during the load phase.
.TP
.BR 5 " (EXIT_SIGNAL)"
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 \fBAUTOGEN_EXIT_SIGNAL(5)\fP.  Alternatively, AutoGen
may have been interrupted with a \fBkill(2)\fP signal.
.TP
.BR 66 " (EX_NOINPUT)"
A specified configuration file could not be loaded.
.TP
.BR 70 " (EX_SOFTWARE)"
libopts had an internal operational error.  Please report
it to autogen-users@lists.sourceforge.net.  Thank you.
.SH "AUTHORS"
Bruce Korb
.SH "COPYRIGHT"
Copyright (C) 1992-2012 Bruce Korb all rights reserved.
This program is released under the terms of the GNU General Public License, version 3 or later.
.SH "BUGS"
Please send bug reports to: autogen-users@lists.sourceforge.net
.SH "NOTES"
This manual page was \fIAutoGen\fP-erated from the \fBautogen\fP
option definitions.