Go to main content

man pages section 1: User Commands

Exit Print View

Updated: July 2017

autogen (1)


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)

       autogen - The Automated Program Generator

       autogen [-flag [value]]... [--opt-name [[=| ]value]]...
               [ <def-file> ]

       AutoGen creates text files from templates using external definitions.

       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.

       -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
                  assign      group = name_of_some_group
                  assign      init  = _init

                  getdefs load=getdefs.cfg <<source-file-list>>

              Note, however, that your functions must be named:


              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-

              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:
              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:

              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.

              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:

              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).

              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 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

              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

       -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)

              This option specifies that the abbreviated usage text should be

       -?, --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.

       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.

       See attributes(5) for descriptions of the following attributes:

       |Availability   | developer/build/autogen |
       |Stability      | Uncommitted             |
       This program is documented more fully in the AutoGen Info system docu-

           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).

       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-

       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-

       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)