Man Linux: Main Page and Category List

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  briefly  documents 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
       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,
       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
              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) files.

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

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

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

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

       --equate=char-list
              characters considered equivalent.   The  default  char-list  for
              this option is:
                   _-^

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

       --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.  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
              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 server shell.  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
              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.

       --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       debug-message server-shell
                  templates     block-macros  expressions
                  everything
                  or their numeric equivalent.

              The default level for this option is:
                   nothing

              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)

              debug-message Print messages from the "DEBUG" AutoGen macro
              (@pxref{DEBUG}).

              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).
              Additionally, if you rebuild the ‘‘expr.ini’’ file with
              debugging enabled, then all calls to AutoGen defined scheme
              functions will also get logged:
                  cd ${top_builddir}/agen5
                  DEBUG_ENABLED=true bash bootstrap.dir expr.ini
                  make CFLAGS=’-g -DDEBUG_ENABLED=1’

              Be aware tha tyou cannot rebuild this source in this way without
              first having installed the autogen executable in your search
              path.  Because of this, "expr.ini" is in the distributed source
              list, and not in the dependencies.

       --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
              example, --traceout=| less’ will run the trace output through
              the less program.  If it begins with a shell append redirection
              (>>), the output file will be appended to.

       --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
              processing the template.

       --used-defines
              Show the definitions used.  This option may not be preset with
              environment variables or in initialization (rc) files.

              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.

   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} 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 initialization (rc) files.

              Just like ’C’, AutoGen uses #ifdef/#ifndef preprocessing
              directives.  This option will cause the matching names to be
              removed from the list of defined values.

       -?, --help
              Display extended 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 copyright notice.

OPTION PRESETS

       Any option that is not marked as not presettable may be preset 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 ALSO

       This  program  is  documented  more  fully  in  the AutoGen Info system
       documentation.

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

(GNU AutoGen 5.10)                2010-02-10