autogen man page on Mageia

Man page or keyword search:  
man Server   17783 pages
apropos Keyword Search (all sections)
Output format
Mageia logo
[printable version]

autogen(1)			 User Commands			    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
       AutoGen	is  designed for generating program files that contain repeti‐
       tive text with varied substitutions.  The goal is to simplify the main‐
       tenance	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, con‐
       figuration file processing, environment variables and so on.

       All of this can be done mechanically; with  the	proper	templates  and
       this program.

OPTIONS
   The following options select definitions, templates and scheme functions to
       use
       -L dir, --templ-dirs=dir
	      Search for templates in DIR.  This option may appear  an	unlim‐
	      ited number of times.

	      Add a directory to the list of directories autogen searches 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
	      Use  TPL-FILE  for  the template.	 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
	      Load AutoGen macros from TPL-FILE.  This option  may  appear  an
	      unlimited number 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.

	      Do  not  use  this.  Instead, use the INCLUDE macro in your tem‐
	      plate.

	      NOTE: THIS OPTION IS DEPRECATED

       --definitions=file, --no-definitions
	      Read definitions from FILE.  The no-definitions form  will  dis‐
	      able  the	 option.   This	 option	 is  enabled by default.  This
	      option may not be preset with environment variables or  in  ini‐
	      tialization (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.

       --shell=shell
	      name or path name of shell to use.

	      By default, when AutoGen is built, the configuration  is	probed
	      for  a reasonable Bourne-like shell to use for shell script pro‐
	      cessing.	If a particular template needs an alternate shell,  it
	      must  be specified with this option on the command line, with an
	      environment variable (SHELL) or in the configuration/initializa‐
	      tion file.

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

	      On platforms without these functions, the option is accepted but
	      ignored.	fmemopen(POSIX) is not	adequate  because  its	string
	      buffer  is not reallocatable.  open_memstream(POSIX) is also not
	      adequate because the stream is only opened for output.   AutoGen
	      needs  a	reallocatable  buffer  available  for both reading and
	      writing.

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

   The following options modify how output is handled
       -b name, --base-name=name
	      Specify NAME as the base name for output.	 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, see: pseudo macro.

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

       --writable, --not-writable
	      Allow output files to be writable.  The not-writable  form  will
	      disable the option.

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

   The following options are often useful while debugging new templates
       They specify limits that prevent the template from taking  overly  long
       or producing more output than expected.

       --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 seconds, --timeout=seconds
	      Limit server shell operations to SECONDS.	 This option takes an
	      integer number as its argument.  The value of seconds 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 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	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 tem‐
	      plate 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
	      (see: 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).  Addition‐
	      ally, 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 that you 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 a file name, a file that is appended
	      to, 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.	 Appending to a file is specified by
	      preceding the file name with two greater-than characters (>>).

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

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

       -C, --core
	      Leave a core dump on a failure exit.

	      Many systems default to a zero sized core limit.	If the system
	      has the sys/resource.h header and if this option is supplied,
	      then in the failure exit path, autogen will attempt to set the
	      soft core limit to whatever the hard core limit is.  If that
	      does not work, then an administrator must raise the hard core
	      size limit.

   These options can be used to control what gets processed
       in the definitions files and template files" They specify which outputs
       and parts of outputs to produce.

       -s suffix, --skip-suffix=suffix
	      Skip 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.  This
	      option must not appear in combination with any of the following
	      options: select-suffix.

	      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.

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

	      It is entirely equivalent to place this name in the exported
	      environment.  Internally, that is what AutoGen actually does
	      with this option.

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

	      Similar to 'C', AutoGen uses #ifdef/#ifndef preprocessing direc‐
	      tives.  This option will cause the matching names to be removed
	      from the list of defined values.

   This option is used to automate dependency tracking
       -M type, --make-dep[=type]
	      emit make dependency file.  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 behaves fairly closely to the way the -M series of
	      options work with the gcc compiler, except that instead of just
	      emitting the predecessor dependencies, this also emits the suc‐
	      cessor dependencies (output target files).  By default, the out‐
	      put dependency information will be placed in <base-name>.d, but
	      may also be specified with -MF<file>.  The time stamp on this
	      file will be manipulated so that it will be one second older
	      than the oldest primary output file.

	      The target in this dependency file will normally be the depen‐
	      dency file name, but may also be overridden with -MT<targ-name>.
	      AutoGen will not alter the contents of that file, but it may
	      create it and it will adjust the modification time to match the
	      start time.

	      NB: these second letters are part of the option argument, so -MF
	      <file> must have the space character quoted or omitted, and -M
	      "F <file>" is acceptable because the F is part of the option
	      argument.

	      -M may be followed by any of the letters M, F, P, T, Q, D, or G.
	      However, only F, Q, T and P are meaningful.  All but F have
	      somewhat different meanings.  -MT<name> is interpreted as mean‐
	      ing <name> is a sentinel file that will depend on all inputs
	      (templates and definition files) and all the output files will
	      depend on this sentinel file.  It is suitable for use as a real
	      make target.  Q is treated identically to T, except dollar char‐
	      acters ('$') are doubled.	 P causes a special clean (clobber)
	      phoney rule to be inserted into the make file fragment.  An
	      empty rule is always created for building the list of targets.

	      This is the recommended usage:
		    -MFwhatever-you-like.dep -MTyour-sentinel-file -MP
	      and then in your Makefile, make the autogen rule:
		    -include whatever-you-like.dep
		    clean_targets += clean-your-sentinel-file
		  .sp
		    your-sentinel-file:
			autogen -MT$@@ -MF$*.d .....
		  .sp
		    local-clean :
			rm -f $(clean_targets)

	      The modification time on the dependency file is adjusted to be
	      one second before the earliest time stamp of any other output
	      file.  Consequently, it is suitable for use as the sentinel file
	      testifying to the fact the program was successfully run.
	      (-include is the GNU make way of specifying "include it if it
	      exists".	Your make must support that feature or your bootstrap
	      process must create the file.)

	      All of this may also be specified using the DEPENDENCIES_OUTPUT
	      or AUTOGEN_MAKE_DEP environment variables.  If defined, depen‐
	      dency information will be output.	 If defined with white space
	      free text that is something other than true, false, yes, no, 0
	      or 1, then the string is taken to be an output file name.	 If it
	      contains a string of white space characters, the first token is
	      as above and the second token is taken to be the target (sen‐
	      tinel) file as -MT in the paragraphs above.  DEPENDENCIES_OUTPUT
	      will be ignored if there are multiple sequences of white space
	      characters or if its contents are, specifically, false, no or 0.

   help, version and option handling
       -?, --help
	      Display usage information and exit.

       -!, --more-help
	      Pass the extended usage information through a pager.

       -> [cfgfile], --save-opts[=cfgfile]
	      Save the option state to cfgfile.	 The default is the last con‐
	      figuration file listed in the OPTION PRESETS section, below.
	      The command will exit after updating the config file.

       -< cfgfile, --load-opts=cfgfile, --no-load-opts
	      Load options from cfgfile.  The no-load-opts form will disable
	      the loading of earlier config/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.

ENVIRONMENT
       See OPTION PRESETS for configuration environment variables.

FILES
       See OPTION PRESETS for configuration files.

EXAMPLES
       Here is how the man page is produced:
	   autogen -Tagman-cmd.tpl -MFman-dep -MTstamp-man 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 agman-cmd.tpl.  It also sets the make file depen‐
       dency output to man-dep and the sentinel	 file  (time  stamp  file)  to
       man-stamp.   The	 base  of  the	file  name is derived from the defined
       prog-name.

       The texi invocation document is produced via:
	   autogen -Tagtexi-cmd.tpl -MFtexi-dep -MTtexi-stamp opts.def

EXIT STATUS
       One of the following exit values will be returned:

       0 (EXIT_SUCCESS)
	      Successful program execution.

       1 (EXIT_OPTION_ERROR)
	      The command options were misconfigured.

       2 (EXIT_BAD_TEMPLATE)
	      An error was encountered processing the template.

       3 (EXIT_BAD_DEFINITIONS)
	      The definitions could not be deciphered.

       4 (EXIT_LOAD_ERROR)
	      An error was encountered during the load phase.

       128 (EXIT_SIGNAL)
	      autogen exited due to  catching  a  signal.   If	your  template
	      includes	string formatting, a number argument to a "%s" format‐
	      ting element will trigger a segmentation	fault.	 Autogen  will
	      catch the seg fault signal and exit with AUTOGEN_EXIT_SIGNAL(5).
	      Alternatively, AutoGen may have been interrupted with a  kill(2)
	      signal.	Subtract  128  from the actual exit code to detect the
	      signal number.

       66 (EX_NOINPUT)
	      A specified configuration file could not be loaded.

       70 (EX_SOFTWARE)
	      libopts had an internal operational error.  Please report it  to
	      autogen-users@lists.sourceforge.net.  Thank you.

AUTHORS
       Bruce Korb

COPYRIGHT
       Copyright  (C)  1992-2013 Bruce Korb all rights reserved.  This program
       is released under the terms of the GNU General Public License,  version
       3 or later.

BUGS
       Please send bug reports to: autogen-users@lists.sourceforge.net

NOTES
       This  manual  page  was	AutoGen-erated from the autogen option defini‐
       tions.

GNU AutoGen (5.18.1)		  08 Sep 2013			    autogen(1)
[top]

List of man pages available for Mageia

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net