diff options
Diffstat (limited to 'agen5/autogen.1')
| -rw-r--r-- | agen5/autogen.1 | 559 |
1 files changed, 559 insertions, 0 deletions
diff --git a/agen5/autogen.1 b/agen5/autogen.1 new file mode 100644 index 0000000..ab9f82f --- /dev/null +++ b/agen5/autogen.1 @@ -0,0 +1,559 @@ +.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. |