Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
autogen(1)			 User Commands			    autogen(1)

       autogen - The Automated Program Generator

       autogen	[-flags]  [-flag  [value]] [--option-name[[=| ]value]] [ <def-
       file> ]

       AutoGen creates text files from templates using external	definitions.

       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.

   The following options select	definitions, templates and scheme functions to
       -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 in-
	      cluded one.  The last entry has  the  highest  priority  in  the
	      search  list.   That is to say, they are searched	in reverse or-

       -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 ex-
	      panded.  This option will	override that name and expand  a  dif-
	      ferent template.

       --definitions=file, --no-definitions
	      Read  definitions	 from FILE.  The no-definitions	form will dis-
	      able the option.	This option is enabled by default.   This  op-
	      tion may not be preset with environment variables	or in initial-
	      ization (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  ac-
	      tive AutoGen definitions.

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

	      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

	      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)

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

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

	      tracing level of detail.	This option takes a keyword as its ar-
	      gument.  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
		  or their numeric equivalent.

	      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)

	      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	en-
	      abled, 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.

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

	      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.  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 un-
	      limited number of	times.	This option may	not be preset with en-
	      vironment	variables or in	initialization (rc) files.  This op-
	      tion 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 un-
	      limited 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 re-
	      trieve a specific	value.	That index may also be a define-d

	      It is entirely equivalent	to place this name in the exported en-
	      vironment.  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 un-
	      limited number of	times.	This option may	not be preset with en-
	      vironment	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 ar-

	      -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
			autogen	-MT$@@ -MF$*.d .....
		    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.	(-in-
	      clude is the GNU make way	of specifying "include it if it	ex-
	      ists".  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, option and error handling
	      Do not abort on errors.

	      By default, AutoGen will abort on	an error leaving behind	a core
	      image.  That is sometimes	inconvenient. If present on the	com-
	      mand line	or in the environment, AutoGen will call exit(1) in-
	      stead of abort().

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

       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 OPTION PRESETS for configuration environment	variables.

       See OPTION PRESETS for configuration files.

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

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

       One of the following exit values	will be	returned:

       0  (EXIT_SUCCESS)
	      Successful program execution.

	      The command options were misconfigured.

	      An error was encountered processing the template.

	      The definitions could not	be deciphered.

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

       5  (EXIT_FS_ERROR)
	      a	file system error stopped the program.

       6  (EXIT_NO_MEM)
	      Insufficient memory to operate.

       128  (EXIT_SIGNAL)
	      autogen exited due to catching a signal.	If your	 template  in-
	      cludes string formatting,	a number argument to a "%s" formatting
	      element will trigger a segmentation fault.  Autogen  will	 catch
	      the  seg fault signal and	exit with AUTOGEN_EXIT_SIGNAL(5).  Al-
	      ternatively, 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  Thank you.

       Bruce Korb

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

       Please send bug reports to:

       This  manual  page  was	AutoGen-erated from the	autogen	option defini-

GNU AutoGen (5.18.16)		  26 Aug 2018			    autogen(1)


Want to link to this manual page? Use this URL:

home | help