autogen - The Automated Program Generator
autogen [-flag [value]]... [--opt-name [[=| ]value]]... [ <def-file> ] AutoGen creates text files from templates using external definitions.
AUTOGEN(1) Programmer's Manual 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 contain repetitive text with varied substitutions. The goal is to simplify the maintenance of pro- grams that contain large amounts of repetitious text. This is espe- cially 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, rc/ini file processing, environment variables and so on. All of this can be done mechanically; with the proper templates and this program. OPTIONS -L dir, --templ-dirs=dir Template search directory list. This option may appear an unlimited number of times. Add a directory to the list of directories to search when open- ing a template, either as the primary template or an included one. The last entry has the highest priority in the search list. That is to say, they are searched in reverse order. -T tpl-file, --override-tpl=tpl-file Override template file. This option may not be preset with environment variables or in initialization (rc) files. Definition files specify the standard template that is to be expanded. This option will override that name and expand a dif- ferent template. -l tpl-file, --lib-template=tpl-file Library template file. This option may appear an unlimited num- ber of times. DEFINE macros are saved from this template file for use in pro- cessing the main macro file. Template text aside from the DEFINE macros is is ignored. -b name, --base-name=name Base name for output file(s). This option may not be preset with environment variables or in initialization (rc) files. A template may specify the exact name of the output file. Nor- mally, it does not. Instead, the name is composed of the base name of the definitions file with suffixes appended. This option will override the base name derived from the definitions file name. This is required if there is no definitions file and advisable if definitions are being read from stdin. If the def- initions are being read from standard in, the base name defaults to stdin. Any leading directory components in the name will be silently removed. If you wish the output file to appear in a particular directory, it is recommended that you "cd" into that directory first, or use directory names in the format specifica- tion for the output suffix lists, @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 variables or in initialization (rc) files. Use this argument to specify the input definitions file with a command line option. If you do not specify this option, then there must be a command line argument that specifies the file, even if only to specify stdin with a hyphen (-). Specify, --no- definitions when you wish to process a template without any active AutoGen definitions.\n -S file, --load-scheme=file Scheme code file to load. Use this option to pre-load Scheme scripts into the Guile inter- preter before template processing begins. Please note that the AutoGen specific functions are not loaded until after argument processing. So, though they may be specified in lambda func- tions you define, they may not be invoked until after option processing is complete. -F file, --load-functions=file Load scheme function library. This option is used to load Guile-scheme functions. The auto- matically called initialization routine scm_init must be used to register these routines or data. This routine can be generated by using the following 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 out- put files specified in the template. (For example, only the .h header file, but not the .c program text.) To do this specify --skip-suffix=c on the command line. -o suffix, --select-suffix[=suffix] specify this output suffix. This option may appear an unlimited number of times. This option may not be preset with environment variables or in initialization (rc) files. If you wish to override the suffix specifications in the tem- plate, you can use one or more copies of this option. See the suffix specification in the @ref{pseudo macro} section of the info doc. --source-time, --no-source-time set mod times to latest source. The no-source-time form will disable the option. If you stamp your output files with the `DNE' macro output, then your output files will always be different, even if the content has not really changed. If you use this option, then the modi- fication time of the output files will change only if the input files change. This will help reduce unneeded builds. -m, --no-fmemopen Do not use in-mem streams. If the local C library supports "fopencookie(3GNU)", or "funopen(3BSD)" then AutoGen prefers to use in-memory stream buffer opens instead of anonymous files. This may lead to prob- lems if there is a shortage of virtual memory. If, for a par- ticular application, you run out of memory, then specify this option. This is unlikely in a modern virtual memory environ- ment. --equate=char-list characters considered equivalent. The default char-list for this option is: _-^ This option will alter the list of characters considered equiva- lent. The default are the three characters, "_-^". (The last is conventional on a Tandem/HP-NonStop, and I used to do a lot of work on Tandems.) --writable, --not-writable Allow output files to be writable. The not-writable form will disable the option. This option may not be preset with environ- ment variables or in initialization (rc) files. This option will leave output files writable. Normally, output files are read-only. The following options are often useful while debugging new templates: --loop-limit=lim Limit on increment loops. This option takes an integer number as its argument. The value of lim is constrained to being: exactly -1, or in the range 1 through 0x1000000 The default lim for this option is: 256 This option prevents runaway loops. For example, if you acci- dentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)", it will take a long time to finish. If you do have more than 256 entries in tables, you will need to specify a new limit with this option. -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 constrained to being: in the range 0 through 3600 AutoGen works with a shell server process. Most normal commands will complete in less than 10 seconds. If, however, your com- mands need more time than this, use this option. The valid range is 0 to 3600 seconds (1 hour). Zero will dis- able the server time limit. --trace=level tracing level of detail. This option takes a keyword as its argument. The argument sets an enumeration value that can be tested by comparing them against the option value macro. The available keywords are: nothing 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 tem- plate 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" initialization script about 30 lines long. Its output is discarded and not inserted into any template. templates Traces the invocation of DEFINEd macros and INCLUDEs block-macros Traces all block macros. The above, plus IF, FOR, CASE and WHILE. expressions Displays the results of expression evaluations. everything Displays the invocation of every AutoGen macro, even TEXT macros (i.e. the text outside of macro quotes). --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 standard in. For exam- ple, --traceout='| less' will run the trace output through the less program. --show-defs Show the definition tree. This option may not be preset with environment variables or in initialization (rc) files. This will print out the complete definition tree before process- ing the template. 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 directives. 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. 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. 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@} refer- ences 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 initialization (rc) files. Just like 'C', AutoGen uses #ifdef/#ifndef preprocessing direc- tives. 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 initialization (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 con- figuration file listed in the OPTION PRESETS section, below. -< rcfile, --load-opts=rcfile, --no-load-opts Load options from rcfile. The no-load-opts form will disable the loading of earlier RC/INI files. --no-load-opts is handled early, out of order. -v [{v|c|n}], --version[={v|c|n}] Output version of program and exit. The default mode is `v', a simple version. The `c' mode will print copyright information and `n' will print the full copyright notice. OPTION PRESETS Any option that is not marked as not presettable may be preset by load- ing values from configuration ("RC" or ".INI") file(s) and values from environment variables named: AUTOGEN_<option-name> or AUTOGEN The environmental presets take precedence (are processed later than) the configuration files. The homerc files are "$HOME", and ".". If any of these are directories, then the file .autogenrc is searched for within those directories. 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 docu- mentation. 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 normally derived from the input definition file name (viz. opts). AUTHOR Bruce Korb Please send bug reports to: autogen-users@lists.sourceforge.net Released under the GNU General Public License. This manual page was AutoGen-erated from the autogen option defini- tions. 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/auto- gen-5.9.tar.gz Further information about this software can be found on the open source community website at http://www.gnu.org/software/autogen/. (GNU AutoGen 5.9) 2015-08-19 AUTOGEN(1)