autogen_back

AutoGen's Generated Man Page

Main
AutoGen
Pages

Home
Announce
FAQ
docs
XML Defs
testimonials
downloads

Automated
Options

AutoOpts
Comparison
Man example
Redistribute
Licensing
local use
using getopt

GCC's
Fixincludes

fixincludes

Automated
FSM

description
example
usagefsm

Addons
addon

Project GNU
Home Page

Automated
XDR

xdr project

i

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  a  tool designed for generating program files
       that contain repetitive text  with  varied  substitutions.
       Its  goal  is to simplify the maintenance of programs 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 imple­
       ment long option names, rc/ini file  processing,  environ­
       ment variables and so on.

       All of this can be done mechanically; with the proper tem­
       plates 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  pri­
              mary  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 initializa­
              tion (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 initial­
              ization (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.

       --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  envi­
              ronment  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.

       -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 pro­
              cessing.  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 callout library.

              This  option  is  used to load Guile-scheme callout
              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.

                  GRP_NAME=whateveryoulike
                  eopt="subblock=exparg=arg_name,arg_desc,arg_optional,arg_list"
                  eopt="$eopt defs=gfunc templ=snarf srcfile"
                  eopt="assign=group=${GRP_NAME} assign=init=_init $eopt"
                  eopt="$eopt autogen=${AG} base-name=expr"
                  getdefs $eopt <<source-file-list>>

              Note, however, that your functions must be named:

                  whateveryoulike_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-suf­
              fix=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 initial­
              ization (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 dif­
              ferent, 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.

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

              This  option will alter the list of characters con­
              sidered equivalent.   The  default  are  the  three
              characters,  "_-^".  (The latter is conventional on
              a Tandem, and I do a lot of work on the Tandem.)

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

       --loop-limit=lim
              Limit on increment loops.  The default lim for this
              opton 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 servers.  The default  time-lim  for
              this opton is 10.

              AutoGen  works  with  a shell server process.  Most
              normal commands will complete in less than 10  sec­
              onds.   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.   The default level for
              this opton is nothing.

              This option will cause AutoGen to display  a  trace
              of its template processing.  There are five levels:

              Does no tracing at all (default)

              Traces  the  invocation  of  DEFINEd   macros   and
              INCLUDEs

              Traces  all block macros.  The above, plus IF, FOR,
              CASE and WHILE.

              Displays the results of expression evaluations

              Displays the invocation  of  every  AutoGen  macro,
              even TEXT macros.

       --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  opera­
              tor  (|),  a  command that will receive the tracing
              output as standard in.  For example,  --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 initializa­
              tion (rc) files.

              This will print out the  complete  definition  tree
              before processing the template.

       --show-shell
              Show shell commands.  This option may not be preset
              with environment  variables  or  in  initialization
              (rc) files.

              This will cause set -x to be executed in the shell,
              with the  resultant  output  printed  to  /dev/tty.
              This  option will have no effect if --disable-shell
              was specified at configure time.

       -D value, --define=value
              name to add to definition list.   This  option  may
              appear  an  unlimited number of times.  This option
              is a member of the define class of options.

              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.
              That  part of the name string will be replaced with
              the define-d value for 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.  This option is a member
              of the define class of options.

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

       -?, --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 rc file listed in the OPTION PRESETS  sec­
              tion, 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 RC (.ini) file(s) and values
       from environment variables named:
         AUTOGEN_<option-name>
       The environmental presets take precedence  (are  processed
       later  than)  the RC 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 speci­
       fied 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-bugs@sf.net

       Released under the GNU General Public License.

       This  manual  page  was  AutoGen-erated  from  the autogen
       option definitions.

                            2002-09-21                 AUTOGEN(1)
This man page was converted to HTML by man2html

top  Viewable With Any Browser  Valid XHTML 1.0!


AutoGen, AutoOpts, columns, getdefs, AutoFSM, AutoXDR and these web pages copyright (c) 1999-2002 Bruce Korb, all rights reserved.

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to webmasters@www.gnu.org, send other questions to gnu@gnu.org.

This article, Copyright © 2000-2002 by Bruce Korb

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. Last modified: Sun Oct 1 12:59:20 PDT 2006