diff options
Diffstat (limited to 'agen5/invoke-autogen.texi')
| -rw-r--r-- | agen5/invoke-autogen.texi | 872 |
1 files changed, 872 insertions, 0 deletions
diff --git a/agen5/invoke-autogen.texi b/agen5/invoke-autogen.texi new file mode 100644 index 0000000..31c65f9 --- /dev/null +++ b/agen5/invoke-autogen.texi @@ -0,0 +1,872 @@ +@node autogen Invocation +@chapter Invoking autogen +@pindex autogen +@cindex The Automated Program Generator +@ignore +# -*- buffer-read-only: t -*- vi: set ro: +# +# DO NOT EDIT THIS FILE (invoke-autogen.texi) +# +# It has been AutoGen-ed August 11, 2012 at 09:41:40 AM by AutoGen 5.16.2pre7 +# From the definitions /old-home/bkorb/ag/ag/agen5/opts.def +# and the template file agtexi-cmd.tpl +@end ignore + +AutoGen creates text files from templates using external definitions. + +@code{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 @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{autogen} program. +This software is released under the GNU General Public License, version 3 or later. + +@menu +* autogen usage:: autogen help/usage (@option{--help}) +* autogen input-select:: input-select options +* autogen out-handling:: out-handling options +* autogen debug-tpl:: debug-tpl options +* autogen processing:: processing options +* autogen dep-track:: dep-track options +* autogen config:: presetting/configuring autogen +* autogen exit status:: exit status +* autogen Examples:: Examples +@end menu + +@node autogen usage +@section autogen help/usage (@option{--help}) +@cindex autogen help + +This is the automatically generated usage text for autogen. + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example +autogen (GNU AutoGen) - The Automated Program Generator - Ver. 5.16.2pre7 +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 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 + 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 + 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 Base name for output file(s) + - 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 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 + -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 Omit the file with this suffix + - prohibits these options: + 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 + +version, usage and configuration options: + + 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 (2012-08-10) +Report autogen bugs to bkorb@@gnu.org +@end example +@exampleindent 4 + +@node autogen input-select +@section input-select options +The following options select definitions, templates and scheme functions to use. +@subheading templ-dirs option (-L). +@anchor{autogen templ-dirs} +@cindex autogen-templ-dirs + +This is the ``template search directory list'' option. +This option takes an argument string @file{dir}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +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. +@subheading override-tpl option (-T). +@anchor{autogen override-tpl} +@cindex autogen-override-tpl + +This is the ``override template file'' option. +This option takes an argument string @file{tpl-file}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + +Definition files specify the standard template that is to be expanded. +This option will override that name and expand a different template. +@subheading lib-template option (-l). +@anchor{autogen lib-template} +@cindex autogen-lib-template + +This is the ``library template file'' option. +This option takes an argument string @file{tpl-file}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +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. +@subheading definitions option. +@anchor{autogen definitions} +@cindex autogen-definitions + +This is the ``definitions input file'' option. +This option takes an argument string @file{file}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +is enabled by default. +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + +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 (@code{-}). +Specify, @code{--no-definitions} when you wish to process +a template without any active AutoGen definitions. +@subheading load-scheme option (-S). +@anchor{autogen load-scheme} +@cindex autogen-load-scheme + +This is the ``scheme code file to load'' option. +This option takes an argument string @file{file}. +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. +@subheading load-functions option (-F). +@anchor{autogen load-functions} +@cindex autogen-load-functions + +This is the ``load scheme function library'' option. +This option takes an argument string @file{file}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_DLOPEN} during the compilation. +@end itemize + +This option is used to load Guile-scheme functions. The automatically +called initialization routine @code{scm_init} must be used to register +these routines or data. +@subheading shell option. +@anchor{autogen shell} +@cindex autogen-shell + +This is the ``name or path name of shell to use'' option. +This option takes an argument string @file{shell}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SHELL_ENABLED} during the compilation. +@end itemize + +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 +(@code{SHELL}) or in the configuration/initialization file. +@subheading no-fmemopen option (-m). +@anchor{autogen no-fmemopen} +@cindex autogen-no-fmemopen + +This is the ``do not use in-mem streams'' option. +If the local C library supports "@code{fopencookie(3GNU)}", or +"@code{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. @code{fmemopen(POSIX)} is not adequate because +its string buffer is not reallocatable. @code{open_memstream(POSIX)} +is @i{also} not adequate because the stream is only opened for +output. AutoGen needs a reallocatable buffer available for both +reading and writing. +@subheading equate option. +@anchor{autogen equate} +@cindex autogen-equate + +This is the ``characters considered equivalent'' option. +This option takes an argument string @file{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.) +@node autogen out-handling +@section out-handling options +The following options modify how output is handled. +@subheading base-name option (-b). +@anchor{autogen base-name} +@cindex autogen-base-name + +This is the ``base name for output file(s)'' option. +This option takes an argument string @file{name}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + +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 @file{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}. +@subheading source-time option. +@anchor{autogen source-time} +@cindex autogen-source-time + +This is the ``set mod times to latest source'' option. +If you stamp your output files with the @code{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. +@subheading writable option. +@anchor{autogen writable} +@cindex autogen-writable + +This is the ``allow output files to be writable'' option. +This option will leave output files writable. +Normally, output files are read-only. +@node autogen debug-tpl +@section debug-tpl options +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. +@subheading loop-limit option. +@anchor{autogen loop-limit} +@cindex autogen-loop-limit + +This is the ``limit on increment loops'' option. +This option takes an argument number @file{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. +@subheading timeout option (-t). +@anchor{autogen timeout} +@cindex autogen-timeout + +This is the ``time limit for server shell'' option. +This option takes an argument number @file{time-lim}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SHELL_ENABLED} during the compilation. +@end itemize + +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. +@subheading trace option. +@anchor{autogen trace} +@cindex autogen-trace + +This is the ``tracing level of detail'' option. +This option takes an argument keyword @file{level}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +This option takes a keyword as its argument. +The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_TRACE). +The available keywords are: +@example + nothing debug-message server-shell + templates block-macros expressions + everything +@end example + +or their numeric equivalent.@end itemize + +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: + +@table @samp +@item nothing +Does no tracing at all (default) + +@item debug-message +Print messages from the "DEBUG" AutoGen macro (@pxref{DEBUG}). + +@item 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. + +@item templates +Traces the invocation of @code{DEFINE}d macros and @code{INCLUDE}s + +@item block-macros +Traces all block macros. The above, plus @code{IF}, @code{FOR}, +@code{CASE} and @code{WHILE}. + +@item expressions +Displays the results of expression evaluations. + +@item everything +Displays the invocation of every AutoGen macro, even @code{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: +@* +@example +cd $@{top_builddir@}/agen5 +DEBUG_ENABLED=true bash bootstrap.dir expr.ini +make CFLAGS='-g -DDEBUG_ENABLED=1' +@end example + +Be aware that you cannot rebuild this source in this way without first +having installed the @code{autogen} executable in your search path. +Because of this, "expr.ini" is in the distributed source list, and +not in the dependencies. +@end table +@subheading trace-out option. +@anchor{autogen trace-out} +@cindex autogen-trace-out + +This is the ``tracing output file or filter'' option. +This option takes an argument string @file{file}. +The output specified may be a file name, a file that is appended to, +or, if the option argument begins with the @code{pipe} operator +(@code{|}), a command that will receive the tracing output as standard +in. For example, @code{--traceout='| less'} will run the trace output +through the @code{less} program. Appending to a file is specified by +preceeding the file name with two greater-than characters (@code{>>}). +@subheading show-defs option. +@anchor{autogen show-defs} +@cindex autogen-show-defs + +This is the ``show the definition tree'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{DEBUG_ENABLED} during the compilation. +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + +This will print out the complete definition tree before processing +the template. +@subheading used-defines option. +@anchor{autogen used-defines} +@cindex autogen-used-defines + +This is the ``show the definitions used'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + +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. +@subheading core option (-C). +@anchor{autogen core} +@cindex autogen-core + +This is the ``leave a core dump on a failure exit'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_SYS_RESOURCE_H} during the compilation. +@end itemize + +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. +@node autogen processing +@section processing options +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. +@subheading skip-suffix option (-s). +@anchor{autogen skip-suffix} +@cindex autogen-skip-suffix + +This is the ``omit the file with this suffix'' option. +This option takes an argument string @file{suffix}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@item +may not be preset with environment variables or configuration (rc/ini) files. +@item +must not appear in combination with any of the following options: +select-suffix. +@end itemize + +Occasionally, it may not be desirable to produce all of the output +files specified in the template. (For example, only the @file{.h} +header file, but not the @file{.c} program text.) To do this +specify @code{--skip-suffix=c} on the command line. +@subheading select-suffix option (-o). +@anchor{autogen select-suffix} +@cindex autogen-select-suffix + +This is the ``specify this output suffix'' option. +This option takes an argument string @file{suffix}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + +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. +@subheading define option (-D). +@anchor{autogen define} +@cindex autogen-define + +This is the ``name to add to definition list'' option. +This option takes an argument string @file{value}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +The AutoGen define names are used for the following purposes: + +@enumerate +@item +Sections of the AutoGen definitions may be enabled or disabled +by using C-style #ifdef and #ifndef directives. +@item +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. +@item +The name of a file may be prefixed with @code{$NAME/}. +The @code{$NAME} part of the name string will be replaced with +the define-d value for @code{NAME}. +@item +When AutoGen is finished loading the definitions, the defined values +are exported to the environment with, @code{putenv(3)}. +These values can then be used in shell scripts with @code{$@{NAME@}} +references and in templates with @code{(getenv "NAME")}. +@item +While processing a template, you may specify an index to retrieve +a specific value. That index may also be a define-d value. +@end enumerate + +It is entirely equivalent to place this name in the exported environment. +Internally, that is what AutoGen actually does with this option. +@subheading undefine option (-U). +@anchor{autogen undefine} +@cindex autogen-undefine + +This is the ``definition list removal pattern'' option. +This option takes an argument string @file{name-pat}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + +Similar to 'C', AutoGen uses @code{#ifdef/#ifndef} preprocessing +directives. This option will cause the matching names to be +removed from the list of defined values. +@node autogen dep-track +@section dep-track options +This option is used to automate dependency tracking. +@subheading make-dep option (-M). +@anchor{autogen make-dep} +@cindex autogen-make-dep + +This is the ``emit make dependency file'' option. +This option takes an optional argument string @file{type}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@item +may not be preset with environment variables or configuration (rc/ini) files. +@end itemize + + +This option behaves fairly closely to the way the @code{-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 @code{<base-name>.d}, but may also be +specified with @code{-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 @code{-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. + +@strong{NB:} these second letters are part of the option argument, so +@code{-MF <file>} must have the space character quoted or omitted, and +@code{-M "F <file>"} is acceptable because the @code{F} is part of the +option argument. + +@code{-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. @code{-MT<name>} is interpreted as meaning +@code{<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: +@example + -MFwhatever-you-like.dep -MTyour-sentinel-file -MP +@end example +and then in your @code{Makefile}, make the @file{autogen} rule: +@example + -include whatever-you-like.dep + clean_targets += clean-your-sentinel-file + + your-sentinel-file: + autogen -MT$@@ -MF$*.d ..... + + local-clean : + rm -f $(clean_targets) +@end example + +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. (@code{-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 @code{DEPENDENCIES_OUTPUT} +or @code{AUTOGEN_MAKE_DEP} environment variables. If defined, +dependency information will be output. If defined with white space +free text that is something other than @code{true}, @code{false}, +@code{yes}, @code{no}, @code{0} or @code{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 @code{-MT} in the paragraphs +above. @code{DEPENDENCIES_OUTPUT} will be ignored if there are +multiple sequences of white space characters or if its contents are, +specifically, @code{false}, @code{no} or @code{0}. + + +@node autogen config +@section presetting/configuring autogen + +Any option that is not marked as @i{not presettable} may be preset by +loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{AUTOGEN} and @code{AUTOGEN_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of +the options listed above in upper case and segmented with underscores. +The @code{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. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{autogen} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.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: +@example +[AUTOGEN] +@end example +@noindent +or by +@example +<?program autogen> +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example +<option-name> + <sub-opt>...<...>...</sub-opt> +</option-name> +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{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: + +@subheading version (-v) + +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: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@subheading usage (-u) + +Print abbreviated usage to standard out, then exit 0. + +@subheading reset-option (-R) + +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. + +@node autogen exit status +@section autogen exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_OPTION_ERROR) +The command options were misconfigured. +@item 2 (EXIT_BAD_TEMPLATE) +An error was encountered processing the template. +@item 3 (EXIT_BAD_DEFINITIONS) +The definitions could not be deciphered. +@item 4 (EXIT_LOAD_ERROR) +An error was encountered during the load phase. +@item 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 @code{AUTOGEN_EXIT_SIGNAL(5)}. Alternatively, AutoGen +may have been interrupted with a @code{kill(2)} signal. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node autogen Examples +@section autogen Examples +Here is how the man page is produced: +@example +autogen -Tagman-cmd.tpl -MFman-dep -MTstamp-man opts.def +@end example + +This command produced this man page from the AutoGen option definition +file. It overrides the template specified in @file{opts.def} (normally +@file{options.tpl}) and uses @file{agman-cmd.tpl}. It also sets the +make file dependency output to @file{man-dep} and the sentinel file +(time stamp file) to @file{man-stamp}. The base of the file name is +derived from the defined @code{prog-name}. + +The texi invocation document is produced via: +@example +autogen -Tagtexi-cmd.tpl -MFtexi-dep -MTtexi-stamp opts.def +@end example + |