man pages section 1: User Commands

Exit Print View

Updated: July 2014

autogen (1)


autogen - The Automated Program Generator


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

AutoGen  creates  text  files  from templates using external


User Commands                                          AUTOGEN(1)

     autogen - The Automated Program Generator

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

     AutoGen  creates  text  files  from templates using external

     This manual page documents, briefly,  the  autogen  command.
     AutoGen  is  designed for generating program files that con-
     tain 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 syn-

     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 vari-
     ables and so on.

     All  of  this can be done mechanically; with the proper tem-
     plates 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 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.

     -T tpl-file, --override-tpl=tpl-file
          Override  template file.  This option may not be preset
          with environment variables or  in  initialization  (rc)

          Definition  files specify the standard template that is
          to be expanded.  This option will  override  that  name
          and expand a different template.

(GNU AutoGen 5.9)    Last change: 2014-06-17                    1

User Commands                                          AUTOGEN(1)

     -l tpl-file, --lib-template=tpl-file
          Library  template  file.   This  option  may  appear an
          unlimited number of times.

          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.

     -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.   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 defi-
          nitions  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 specification 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 vari-
          ables 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 defi-

     -S file, --load-scheme=file
          Scheme code file to load.

          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.

(GNU AutoGen 5.9)    Last change: 2014-06-17                    2

User Commands                                          AUTOGEN(1)

     -F file, --load-functions=file
          Load scheme function library.

          This option is used  to  load  Guile-scheme  functions.
          The   automatically   called   initialization   routine
          scm_init must be used to  register  these  routines  or
          data.   This routine can be generated by using the fol-
          lowing 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 output files specified in the template.  (For exam-
          ple, only the .h header file, but not  the  .c  program
          text.)   To do this specify --skip-suffix=c on the com-
          mand line.

     -o suffix, --select-suffix[=suffix]
          specify this output suffix.  This option may appear  an
          unlimited number of times.  This option may not be pre-
          set with environment  variables  or  in  initialization
          (rc) files.

          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

(GNU AutoGen 5.9)    Last change: 2014-06-17                    3

User Commands                                          AUTOGEN(1)

          @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  differ-
          ent,  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.

     -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 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 virtual memory environment.

          characters considered equivalent.   The  default  char-
          list for this option is:

          This  option  will alter the list of characters consid-
          ered equivalent.  The default are the three characters,
          "_-^".   (The  last is conventional on a Tandem/HP-Non-
          Stop, 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 environment variables or in  initialization
          (rc) files.

          This  option  will  leave  output files writable.  Nor-
          mally, output files are read-only.

  The following options are often useful while debugging new tem-
          Limit on increment loops.  This option takes an integer
          number as its argument.   The  value  of  lim  is  con-
          strained to being:
              exactly -1, or
              in the range  1 through 0x1000000
          The default lim for this option is:

(GNU AutoGen 5.9)    Last change: 2014-06-17                    4

User Commands                                          AUTOGEN(1)


          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.

     -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 con-
          strained 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 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.

          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 template 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" initializa-
          tion script about 30 lines long.  Its output is dis-
          carded and not inserted into any template.

          templates Traces the invocation of DEFINEd macros and

          block-macros Traces all block macros.  The above, plus

(GNU AutoGen 5.9)    Last change: 2014-06-17                    5

User Commands                                          AUTOGEN(1)

          IF, FOR, CASE and WHILE.

          expressions Displays the results of expression evalua-

          everything Displays the invocation of every AutoGen
          macro, even TEXT macros (i.e. the text outside of macro

          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 stan-
          dard in.  For example, --traceout='| less' will run the
          trace output through the less program.

          Show the definition tree.  This option may not be pre-
          set with environment variables or in initialization
          (rc) files.

          This will print out the complete definition tree before
          processing 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

          Sections of the AutoGen definitions may be enabled or
          disabled by using C-style #ifdef and #ifndef direc-

          When defining a value for a name, you may specify the
          index for a particular value.  That index may be a lit-
          eral 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.

(GNU AutoGen 5.9)    Last change: 2014-06-17                    6

User Commands                                          AUTOGEN(1)

          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@} references 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 initial-
          ization (rc) files.

          Just like 'C', AutoGen uses #ifdef/#ifndef preprocess-
          ing directives.  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
     by AutoOpts:"

     -h, --short-help
          Get short help text without an error exit.  This option
          may not be preset with environment variables or in ini-
          tialization (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 configuration 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

(GNU AutoGen 5.9)    Last change: 2014-06-17                    7

User Commands                                          AUTOGEN(1)

          copyright notice.

     Any option that is not marked as not presettable may be pre-
     set by loading 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

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

         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 nor-
     mally derived from the input definition file name (viz.

     Bruce Korb
     Please send bug reports to:  autogen-users@lists.source-

     Released under the GNU General Public License.

     This manual page was AutoGen-erated from the autogen option

(GNU AutoGen 5.9)    Last change: 2014-06-17                    8

User Commands                                          AUTOGEN(1)

     This software was built from source available at  The original
     community source was downloaded from

     Further information about this software can be found on the
     open source community website at

(GNU AutoGen 5.9)    Last change: 2014-06-17                    9