1autogen(1)                       User Commands                      autogen(1)
2
3
4

NAME

6       autogen - The Automated Program Generator
7

SYNOPSIS

9       autogen  [-flags]  [-flag  [value]] [--option-name[[=| ]value]] [ <def-
10       file> ]
11
12       AutoGen creates text files from templates using external definitions.
13

DESCRIPTION

15       AutoGen is designed for generating program files that  contain  repeti‐
16       tive text with varied substitutions.  The goal is to simplify the main‐
17       tenance of programs that contain large  amounts  of  repetitious  text.
18       This  is  especially  valuable if there are several blocks of such text
19       that must be kept synchronized.
20
21       One common example is the problem of maintaining the code required  for
22       processing  program  options.  Processing options requires a minimum of
23       four different constructs be kept in proper order in  different  places
24       in  your  program.   You  need at least: The flag character in the flag
25       string, code to process the flag when it is encountered, a global state
26       variable  or  two,  and  a  line in the usage text.  You will need more
27       things besides this if you choose to implement long option names,  con‐
28       figuration file processing, environment variables and so on.
29
30       All  of  this  can  be done mechanically; with the proper templates and
31       this program.
32

OPTIONS

34   The following options select definitions, templates and scheme functions to
35       use
36       -L dir, --templ-dirs=dir
37              Search  for  templates in DIR.  This option may appear an unlim‐
38              ited number of times.
39
40              Add a directory to the list of directories autogen searches when
41              opening  a  template,  either  as  the  primary  template  or an
42              included one.  The last entry has the highest  priority  in  the
43              search  list.   That  is  to  say,  they are searched in reverse
44              order.
45
46       -T tpl-file, --override-tpl=tpl-file
47              Use TPL-FILE for the template.  This option may  not  be  preset
48              with environment variables or in initialization (rc) files.
49
50              Definition  files  specify  the  standard template that is to be
51              expanded.  This option will override that name and expand a dif‐
52              ferent template.
53
54       --definitions=file, --no-definitions
55              Read  definitions  from FILE.  The no-definitions form will dis‐
56              able the option.  This  option  is  enabled  by  default.   This
57              option  may  not be preset with environment variables or in ini‐
58              tialization (rc) files.
59
60              Use this argument to specify the input definitions file  with  a
61              command  line  option.   If you do not specify this option, then
62              there must be a command line argument that specifies  the  file,
63              even if only to specify stdin with a hyphen (-).  Specify, --no-
64              definitions when you wish to  process  a  template  without  any
65              active AutoGen definitions.
66
67       --shell=shell
68              name or path name of shell to use.
69
70              By  default,  when AutoGen is built, the configuration is probed
71              for a reasonable Bourne-like shell to use for shell script  pro‐
72              cessing.   If a particular template needs an alternate shell, it
73              must be specified with this option on the command line, with  an
74              environment variable (SHELL) or in the configuration/initializa‐
75              tion file.
76
77       -m, --no-fmemopen
78              Do not use in-mem streams.
79
80              If  the  local  C  library  supports   "fopencookie(3GNU)",   or
81              "funopen(3BSD)"  then  AutoGen  prefers  to use in-memory stream
82              buffer opens instead of anonymous files.  This may lead to prob‐
83              lems  if  there is a shortage of virtual memory.  If, for a par‐
84              ticular application, you run out of memory,  then  specify  this
85              option.   This  is  unlikely  in  a modern 64-bit virtual memory
86              environment.
87
88              On platforms without these functions, the option is accepted but
89              ignored.   fmemopen(POSIX)  is  not  adequate because its string
90              buffer is not reallocatable.  open_memstream(POSIX) is also  not
91              adequate  because the stream is only opened for output.  AutoGen
92              needs a reallocatable buffer  available  for  both  reading  and
93              writing.
94
95       --equate=char-list
96              characters  considered  equivalent.   The  default char-list for
97              this option is:
98                   _-^
99
100              This option will alter the list of characters considered equiva‐
101              lent.   The  default are the three characters, "_-^".  (The last
102              is conventional on a Tandem/HP-NonStop, and I used to do  a  lot
103              of work on Tandems.)
104
105   The following options modify how output is handled
106       -b name, --base-name=name
107              Specify  NAME  as the base name for output.  This option may not
108              be preset with environment variables or in  initialization  (rc)
109              files.
110
111              A  template may specify the exact name of the output file.  Nor‐
112              mally, it does not.  Instead, the name is composed of  the  base
113              name  of  the  definitions  file  with  suffixes appended.  This
114              option will override the base name derived from the  definitions
115              file name.  This is required if there is no definitions file and
116              advisable if definitions are being read from stdin.  If the def‐
117              initions are being read from standard in, the base name defaults
118              to stdin.  Any leading directory components in the name will  be
119              silently  removed.   If  you wish the output file to appear in a
120              particular directory, it is recommended that you "cd" into  that
121              directory first, or use directory names in the format specifica‐
122              tion for the output suffix lists, see: pseudo macro.
123
124       --source-time, --no-source-time
125              set mod times to latest source.  The  no-source-time  form  will
126              disable the option.
127
128              If  you  stamp your output files with the DNE macro output, then
129              your output files will always be different, even if the  content
130              has  not really changed.  If you use this option, then the modi‐
131              fication time of the output files will change only if the  input
132              files change.  This will help reduce unneeded builds.
133
134       --writable, --not-writable
135              Allow  output  files to be writable.  The not-writable form will
136              disable the option.
137
138              This option will leave output files writable.  Normally,  output
139              files are read-only.
140
141   The following options are often useful while debugging new templates
142       They  specify  limits that prevent the template from taking overly long
143       or producing more output than expected.
144
145       --loop-limit=lim
146              Limit on increment loops.  This option takes an  integer  number
147              as its argument.  The value of lim is constrained to being:
148                  exactly -1, or
149                  in the range  1 through 0x1000000
150              The default lim for this option is:
151                   256
152
153              This option prevents runaway loops.  For example, if you acci‐
154              dentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)",
155              it will take a long time to finish.  If you do have more than
156              256 entries in tables, you will need to specify a new limit with
157              this option.
158
159       -t seconds, --timeout=seconds
160              Limit server shell operations to SECONDS.  This option takes an
161              integer number as its argument.  The value of seconds is con‐
162              strained to being:
163                  in the range  0 through 3600
164
165              AutoGen works with a shell server process.  Most normal commands
166              will complete in less than 10 seconds.  If, however, your com‐
167              mands need more time than this, use this option.
168
169              The valid range is 0 to 3600 seconds (1 hour).  Zero will dis‐
170              able the server time limit.
171
172       --trace=level
173              tracing level of detail.  This option takes a keyword as its
174              argument.  The argument sets an enumeration value that can be
175              tested by comparing them against the option value macro.  The
176              available keywords are:
177                  nothing       debug-message server-shell
178                  templates     block-macros  expressions
179                  everything
180                  or their numeric equivalent.
181
182              The default level for this option is:
183                   nothing
184
185              This option will cause AutoGen to display a trace of its tem‐
186              plate processing.  There are six levels, each level including
187              messages from the previous levels:
188
189
190              nothing Does no tracing at all (default)
191
192
193              debug-message Print messages from the "DEBUG" AutoGen macro
194              (see: DEBUG).
195
196
197              server-shell Traces all input and output to the server shell.
198              This includes a shell "independent" initialization script about
199              30 lines long.  Its output is discarded and not inserted into
200              any template.
201
202
203              templates Traces the invocation of DEFINEd macros and INCLUDEs
204
205
206              block-macros Traces all block macros.  The above, plus IF, FOR,
207              CASE and WHILE.
208
209
210              expressions Displays the results of expression evaluations.
211
212
213              everything Displays the invocation of every AutoGen macro, even
214              TEXT macros (i.e. the text outside of macro quotes).  Addition‐
215              ally, if you rebuild the ``expr.ini'' file with debugging
216              enabled, then all calls to AutoGen defined scheme functions will
217              also get logged:
218                  cd ${top_builddir}/agen5
219                  DEBUG_ENABLED=true bash bootstrap.dir expr.ini
220                  make CFLAGS='-g -DDEBUG_ENABLED=1'
221
222              Be aware that you cannot rebuild this source in this way without
223              first having installed the autogen executable in your search
224              path.  Because of this, "expr.ini" is in the distributed source
225              list, and not in the dependencies.
226
227       --trace-out=file
228              tracing output file or filter.
229
230              The output specified may be a file name, a file that is appended
231              to, or, if the option argument begins with the pipe operator
232              (|), a command that will receive the tracing output as standard
233              in.  For example, --traceout='| less' will run the trace output
234              through the less program.  Appending to a file is specified by
235              preceding the file name with two greater-than characters (>>).
236
237       --show-defs
238              Show the definition tree.  This option may not be preset with
239              environment variables or in initialization (rc) files.
240
241              This will print out the complete definition tree before process‐
242              ing the template.
243
244       --used-defines
245              Show the definitions used.  This option may not be preset with
246              environment variables or in initialization (rc) files.
247
248              This will print out the names of definition values searched for
249              during the processing of the template, whether actually found or
250              not.  There may be other referenced definitions in a template in
251              portions of the template not evaluated.  Some of the names
252              listed may be computed names and others AutoGen macro arguments.
253              This is not a means for producing a definitive, all-encompassing
254              list of all and only the values used from a definition file.
255              This is intended as an aid to template documentation only.
256
257       -C, --core
258              Leave a core dump on a failure exit.
259
260              Many systems default to a zero sized core limit.  If the system
261              has the sys/resource.h header and if this option is supplied,
262              then in the failure exit path, autogen will attempt to set the
263              soft core limit to whatever the hard core limit is.  If that
264              does not work, then an administrator must raise the hard core
265              size limit.  in the definitions files and template files" They
266              specify which outputs and parts of outputs to produce.
267
268       -s suffix, --skip-suffix=suffix
269              Skip the file with this SUFFIX.  This option may appear an
270              unlimited number of times.  This option may not be preset with
271              environment variables or in initialization (rc) files.  This
272              option must not appear in combination with any of the following
273              options: select-suffix.
274
275              Occasionally, it may not be desirable to produce all of the out‐
276              put files specified in the template.  (For example, only the .h
277              header file, but not the .c program text.)  To do this specify
278              --skip-suffix=c on the command line.
279
280       -o suffix, --select-suffix=suffix
281              specify this output suffix.  This option may appear an unlimited
282              number of times.  This option may not be preset with environment
283              variables or in initialization (rc) files.
284
285              If you wish to override the suffix specifications in the tem‐
286              plate, you can use one or more copies of this option.  See the
287              suffix specification in the @ref{pseudo macro} section of the
288              info doc.
289
290       -D value, --define=value
291              name to add to definition list.  This option may appear an
292              unlimited number of times.
293
294              The AutoGen define names are used for the following purposes:
295
296
297              Sections of the AutoGen definitions may be enabled or disabled
298              by using C-style #ifdef and #ifndef directives.
299
300              When defining a value for a name, you may specify the index for
301              a particular value.  That index may be a literal value, a define
302              option or a value #define-d in the definitions themselves.
303
304              The name of a file may be prefixed with $NAME/.  The $NAME part
305              of the name string will be replaced with the define-d value for
306              NAME.
307
308              When AutoGen is finished loading the definitions, the defined
309              values are exported to the environment with, putenv(3).  These
310              values can then be used in shell scripts with ${NAME@} refer‐
311              ences and in templates with (getenv "NAME").
312
313              While processing a template, you may specify an index to
314              retrieve a specific value.  That index may also be a define-d
315              value.
316
317              It is entirely equivalent to place this name in the exported
318              environment.  Internally, that is what AutoGen actually does
319              with this option.
320
321       -U name-pat, --undefine=name-pat
322              definition list removal pattern.  This option may appear an
323              unlimited number of times.  This option may not be preset with
324              environment variables or in initialization (rc) files.
325
326              Similar to 'C', AutoGen uses #ifdef/#ifndef preprocessing direc‐
327              tives.  This option will cause the matching names to be removed
328              from the list of defined values.
329
330   This option is used to automate dependency tracking
331       -M type, --make-dep [type]
332              emit make dependency file.  This option may appear an unlimited
333              number of times.  This option may not be preset with environment
334              variables or in initialization (rc) files.
335
336              This option behaves fairly closely to the way the -M series of
337              options work with the gcc compiler, except that instead of just
338              emitting the predecessor dependencies, this also emits the suc‐
339              cessor dependencies (output target files).  By default, the out‐
340              put dependency information will be placed in <base-name>.d, but
341              may also be specified with -MF<file>.  The time stamp on this
342              file will be manipulated so that it will be one second older
343              than the oldest primary output file.
344
345              The target in this dependency file will normally be the depen‐
346              dency file name, but may also be overridden with -MT<targ-name>.
347              AutoGen will not alter the contents of that file, but it may
348              create it and it will adjust the modification time to match the
349              start time.
350
351              NB: these second letters are part of the option argument, so -MF
352              <file> must have the space character quoted or omitted, and -M
353              "F <file>" is acceptable because the F is part of the option
354              argument.
355
356              -M may be followed by any of the letters M, F, P, T, Q, D, or G.
357              However, only F, Q, T and P are meaningful.  All but F have
358              somewhat different meanings.  -MT<name> is interpreted as mean‐
359              ing <name> is a sentinel file that will depend on all inputs
360              (templates and definition files) and all the output files will
361              depend on this sentinel file.  It is suitable for use as a real
362              make target.  Q is treated identically to T, except dollar char‐
363              acters ('$') are doubled.  P causes a special clean (clobber)
364              phoney rule to be inserted into the make file fragment.  An
365              empty rule is always created for building the list of targets.
366
367              This is the recommended usage:
368                    -MFwhatever-you-like.dep -MTyour-sentinel-file -MP
369              and then in your Makefile, make the autogen rule:
370                    -include whatever-you-like.dep
371                    clean_targets += clean-your-sentinel-file
372                  .sp
373                    your-sentinel-file:
374                        autogen -MT$@@ -MF$*.d .....
375                  .sp
376                    local-clean :
377                        rm -f $(clean_targets)
378
379              The modification time on the dependency file is adjusted to be
380              one second before the earliest time stamp of any other output
381              file.  Consequently, it is suitable for use as the sentinel file
382              testifying to the fact the program was successfully run.
383              (-include is the GNU make way of specifying "include it if it
384              exists".  Your make must support that feature or your bootstrap
385              process must create the file.)
386
387              All of this may also be specified using the DEPENDENCIES_OUTPUT
388              or AUTOGEN_MAKE_DEP environment variables.  If defined, depen‐
389              dency information will be output.  If defined with white space
390              free text that is something other than true, false, yes, no, 0
391              or 1, then the string is taken to be an output file name.  If it
392              contains a string of white space characters, the first token is
393              as above and the second token is taken to be the target (sen‐
394              tinel) file as -MT in the paragraphs above.  DEPENDENCIES_OUTPUT
395              will be ignored if there are multiple sequences of white space
396              characters or if its contents are, specifically, false, no or 0.
397
398   help, version, option and error handling
399       --no-abort
400              Do not abort on errors.
401
402              By default, AutoGen will abort on an error leaving behind a core
403              image.  That is sometimes inconvenient. If present on the com‐
404              mand line or in the environment, AutoGen will call exit(1)
405              instead of abort().
406
407       -?, --help
408              Display usage information and exit.
409
410       -!, --more-help
411              Pass the extended usage information through a pager.
412
413       -> [cfgfile], --save-opts [=cfgfile]
414              Save the option state to cfgfile.  The default is the last con‐
415              figuration file listed in the OPTION PRESETS section, below.
416              The command will exit after updating the config file.
417
418       -< cfgfile, --load-opts=cfgfile, --no-load-opts
419              Load options from cfgfile.  The no-load-opts form will disable
420              the loading of earlier config/rc/ini files.  --no-load-opts is
421              handled early, out of order.
422
423       -v [{v|c|n --version [{v|c|n}]}]
424              Output version of program and exit.  The default mode is `v', a
425              simple version.  The `c' mode will print copyright information
426              and `n' will print the full copyright notice.
427

OPTION PRESETS

429       Any option that is not marked as not presettable may be preset by load‐
430       ing values from configuration ("RC" or ".INI") file(s) and values from
431       environment variables named:
432         AUTOGEN_<option-name> or AUTOGEN
433       The environmental presets take precedence (are  processed  later  than)
434       the  configuration  files.   The homerc files are "$HOME", and ".".  If
435       any of these are directories, then the file .autogenrc is searched  for
436       within those directories.
437

ENVIRONMENT

439       See OPTION PRESETS for configuration environment variables.
440

FILES

442       See OPTION PRESETS for configuration files.
443

EXAMPLES

445       Here is how the man page is produced:
446           autogen -Tagman-cmd.tpl -MFman-dep -MTstamp-man opts.def
447
448       This  command produced this man page from the AutoGen option definition
449       file.  It  overrides  the  template  specified  in  opts.def  (normally
450       options.tpl) and uses agman-cmd.tpl.  It also sets the make file depen‐
451       dency output to man-dep and the sentinel  file  (time  stamp  file)  to
452       man-stamp.   The  base  of  the  file  name is derived from the defined
453       prog-name.
454
455       The texi invocation document is produced via:
456           autogen -Tagtexi-cmd.tpl -MFtexi-dep -MTtexi-stamp opts.def
457

EXIT STATUS

459       One of the following exit values will be returned:
460
461       0  (EXIT_SUCCESS)
462              Successful program execution.
463
464       1  (EXIT_OPTION_ERROR)
465              The command options were misconfigured.
466
467       2  (EXIT_BAD_TEMPLATE)
468              An error was encountered processing the template.
469
470       3  (EXIT_BAD_DEFINITIONS)
471              The definitions could not be deciphered.
472
473       4  (EXIT_LOAD_ERROR)
474              An error was encountered during the load phase.
475
476       5  (EXIT_FS_ERROR)
477              a file system error stopped the program.
478
479       6  (EXIT_NO_MEM)
480              Insufficient memory to operate.
481
482       128  (EXIT_SIGNAL)
483              autogen exited due to  catching  a  signal.   If  your  template
484              includes  string formatting, a number argument to a "%s" format‐
485              ting element will trigger a segmentation  fault.   Autogen  will
486              catch the seg fault signal and exit with AUTOGEN_EXIT_SIGNAL(5).
487              Alternatively, AutoGen may have been interrupted with a  kill(2)
488              signal.   Subtract  128  from the actual exit code to detect the
489              signal number.
490
491       66  (EX_NOINPUT)
492              A specified configuration file could not be loaded.
493
494       70  (EX_SOFTWARE)
495              libopts had an internal operational error.  Please report it  to
496              autogen-users@lists.sourceforge.net.  Thank you.
497

AUTHORS

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

BUGS

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

NOTES

510       This  manual  page  was  AutoGen-erated from the autogen option defini‐
511       tions.
512
513
514
515GNU AutoGen (5.18.16)             26 Aug 2018                       autogen(1)
Impressum