1AUTOGEN(1)                    Programmer's Manual                   AUTOGEN(1)
2
3
4

NAME

6       autogen - The Automated Program Generator
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

35       -L dir, --templ-dirs=dir
36              Template search directory  list.   This  option  may  appear  an
37              unlimited number of times.
38
39              Add  a directory to the list of directories to search when open‐
40              ing a template, either as the primary template  or  an  included
41              one.   The  last  entry  has  the highest priority in the search
42              list.  That is to say, they are searched in reverse order.
43
44       -T tpl-file, --override-tpl=tpl-file
45              Override template file.  This option  may  not  be  preset  with
46              environment variables or in initialization (rc) files.
47
48              Definition  files  specify  the  standard template that is to be
49              expanded.  This option will override that name and expand a dif‐
50              ferent template.
51
52       -l tpl-file, --lib-template=tpl-file
53              Library template file.  This option may appear an unlimited num‐
54              ber of times.
55
56              DEFINE macros are saved from this template file for use in  pro‐
57              cessing  the  main  macro  file.   Template  text aside from the
58              DEFINE macros is is ignored.
59
60       -b name, --base-name=name
61              Base name for output file(s).  This option  may  not  be  preset
62              with environment variables or in initialization (rc) files.
63
64              A  template may specify the exact name of the output file.  Nor‐
65              mally, it does not.  Instead, the name is composed of  the  base
66              name  of  the  definitions  file  with  suffixes appended.  This
67              option will override the base name derived from the  definitions
68              file name.  This is required if there is no definitions file and
69              advisable if definitions are being read from stdin.  If the def‐
70              initions are being read from standard in, the base name defaults
71              to stdin.  Any leading directory components in the name will  be
72              silently  removed.   If  you wish the output file to appear in a
73              particular directory, it is recommended that you "cd" into  that
74              directory first, or use directory names in the format specifica‐
75              tion for the output suffix lists, @xref{pseudo macro}.
76
77       --definitions=file, --no-definitions
78              Definitions input file.  The no-definitions  form  will  disable
79              the option.  This option is enabled by default.  This option may
80              not be preset with environment variables  or  in  initialization
81              (rc) files.
82
83              Use  this  argument to specify the input definitions file with a
84              command line option.  If you do not specify  this  option,  then
85              there  must  be a command line argument that specifies the file,
86              even if only to specify stdin with a hyphen (-).  Specify, --no-
87              definitions  when  you  wish  to  process a template without any
88              active AutoGen definitions.\n
89
90       -S file, --load-scheme=file
91              Scheme code file to load.
92
93              Use this option to pre-load Scheme scripts into the Guile inter‐
94              preter  before template processing begins.  Please note that the
95              AutoGen specific functions are not loaded until  after  argument
96              processing.   So,  though  they may be specified in lambda func‐
97              tions you define, they may not be  invoked  until  after  option
98              processing is complete.
99
100       -F file, --load-functions=file
101              Load scheme function library.
102
103              This  option  is used to load Guile-scheme functions.  The auto‐
104              matically called initialization routine scm_init must be used to
105              register  these routines or data.  This routine can be generated
106              by using the following command  and  the  `snarf.tpl'  template.
107              Read  the  introductory  comment  in `snarf.tpl' to see what the
108              `getdefs(1AG)' comment must contain.
109
110              First, create a config file for getdefs, and then invoke getdefs
111              loading that file:
112                  cat > getdefs.cfg <<EOF
113                  subblock    exparg=arg_name,arg_desc,arg_optional,arg_list
114                  defs-to-get gfunc
115                  template    snarf
116                  srcfile
117                  linenum
118                  assign      group = name_of_some_group
119                  assign      init  = _init
120                  EOF
121
122                  getdefs load=getdefs.cfg <<source-file-list>>
123
124              Note, however, that your functions must be named:
125
126                  name_of_some_group_scm_<<function_name>>(...)
127
128              so you may wish to use a shorter group name.
129
130       -s suffix, --skip-suffix=suffix
131              Omit  the  file  with  this  suffix.   This option may appear an
132              unlimited number of times.  This option may not be  preset  with
133              environment variables or in initialization (rc) files.
134
135              Occasionally, it may not be desirable to produce all of the out‐
136              put files specified in the template.  (For example, only the  .h
137              header  file,  but not the .c program text.)  To do this specify
138              --skip-suffix=c on the command line.
139
140       -o suffix, --select-suffix[=suffix]
141              specify this output suffix.  This option may appear an unlimited
142              number of times.  This option may not be preset with environment
143              variables or in initialization (rc) files.
144
145              If you wish to override the suffix specifications  in  the  tem‐
146              plate,  you  can use one or more copies of this option.  See the
147              suffix specification in the @ref{pseudo macro}  section  of  the
148              info doc.
149
150       --source-time, --no-source-time
151              set  mod  times  to latest source.  The no-source-time form will
152              disable the option.
153
154              If you stamp your output files with the `DNE' macro output, then
155              your  output files will always be different, even if the content
156              has not really changed.  If you use this option, then the  modi‐
157              fication  time of the output files will change only if the input
158              files change.  This will help reduce unneeded builds.
159
160       -m, --no-fmemopen
161              Do not use in-mem streams.
162
163              If  the  local  C  library  supports   "fopencookie(3GNU)",   or
164              "funopen(3BSD)"  then  AutoGen  prefers  to use in-memory stream
165              buffer opens instead of anonymous files.  This may lead to prob‐
166              lems  if  there is a shortage of virtual memory.  If, for a par‐
167              ticular application, you run out of memory,  then  specify  this
168              option.   This  is  unlikely in a modern virtual memory environ‐
169              ment.
170
171       --equate=char-list
172              characters considered equivalent.   The  default  char-list  for
173              this option is:
174                   _-^
175
176              This option will alter the list of characters considered equiva‐
177              lent.  The default are the three characters, "_-^".   (The  last
178              is  conventional  on a Tandem/HP-NonStop, and I used to do a lot
179              of work on Tandems.)
180
181       --writable, --not-writable
182              Allow output files to be writable.  The not-writable  form  will
183              disable the option.  This option may not be preset with environ‐
184              ment variables or in initialization (rc) files.
185
186              This option will leave output files writable.  Normally,  output
187              files are read-only.
188
189   The following options are often useful while debugging new templates:
190       --loop-limit=lim
191              Limit  on  increment loops.  This option takes an integer number
192              as its argument.  The value of lim is constrained to being:
193                  exactly -1, or
194                  in the range  1 through 0x1000000
195              The default lim for this option is:
196                   256
197
198              This option prevents runaway loops.  For example, if you acci‐
199              dentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)",
200              it will take a long time to finish.  If you do have more than
201              256 entries in tables, you will need to specify a new limit with
202              this option.
203
204       -t time-lim, --timeout=time-lim
205              Time limit for servers.  This option takes an integer number as
206              its argument.  The value of time-lim is constrained to being:
207                  in the range  0 through 3600
208
209              AutoGen works with a shell server process.  Most normal commands
210              will complete in less than 10 seconds.  If, however, your com‐
211              mands need more time than this, use this option.
212
213              The valid range is 0 to 3600 seconds (1 hour).  Zero will dis‐
214              able the server time limit.
215
216       --trace=level
217              tracing level of detail.  This option takes a keyword as its
218              argument.  The argument sets an enumeration value that can be
219              tested by comparing them against the option value macro.  The
220              available keywords are:
221                  nothing       debug-message server-shell
222                  templates     block-macros  expressions
223                  everything
224
225              The default level for this option is:
226                   nothing
227
228              This option will cause AutoGen to display a trace of its tem‐
229              plate processing.  There are six levels, each level including
230              messages from the previous levels:
231
232
233              nothing Does no tracing at all (default)
234
235
236              debug-message Print messages from the "DEBUG" AutoGen macro
237              (@pxref{DEBUG}).
238
239
240              server-shell Traces all input and output to the server shell.
241              This includes a shell "independent" initialization script about
242              30 lines long.  Its output is discarded and not inserted into
243              any template.
244
245
246              templates Traces the invocation of DEFINEd macros and INCLUDEs
247
248
249              block-macros Traces all block macros.  The above, plus IF, FOR,
250              CASE and WHILE.
251
252
253              expressions Displays the results of expression evaluations.
254
255
256              everything Displays the invocation of every AutoGen macro, even
257              TEXT macros (i.e. the text outside of macro quotes).  Addition‐
258              ally, if you rebuild the ``expr.ini'' file with debugging
259              enabled, then all calls to AutoGen defined scheme functions will
260              also get logged:
261                  cd ${top_builddir}/agen5
262                  DEBUG_ENABLED=true bash bootstrap.dir expr.ini
263                  make CFLAGS='-g -DDEBUG_ENABLED=1'
264
265              Be aware tha tyou cannot rebuild this source in this way without
266              first having installed the autogen executable in your search
267              path.  Because of this, "expr.ini" is in the distributed source
268              list, and not in the dependencies.
269
270       --trace-out=file
271              tracing output file or filter.
272
273              The output specified may be either a file name, or, if the
274              option argument begins with the pipe operator (|), a command
275              that will receive the tracing output as standard in.  For exam‐
276              ple, --traceout='| less' will run the trace output through the
277              less program.
278
279       --show-defs
280              Show the definition tree.  This option may not be preset with
281              environment variables or in initialization (rc) files.
282
283              This will print out the complete definition tree before process‐
284              ing the template.
285
286   These options can be used to control what gets processed
287       in the definitions files and template files."
288
289       -D value, --define=value
290              name to add to definition list.  This option may appear an
291              unlimited number of times.
292
293              The AutoGen define names are used for the following purposes:
294
295
296              Sections of the AutoGen definitions may be enabled or disabled
297              by using C-style #ifdef and #ifndef directives.
298
299              When defining a value for a name, you may specify the index for
300              a particular value.  That index may be a literal value, a define
301              option or a value #define-d in the definitions themselves.
302
303              The name of a file may be prefixed with $NAME/.  The $NAME part
304              of the name string will be replaced with the define-d value for
305              NAME.
306
307              When AutoGen is finished loading the definitions, the defined
308              values are exported to the environment with, putenv(3).  These
309              values can then be used in shell scripts with ${NAME@} refer‐
310              ences and in templates with (getenv "NAME").
311
312              While processing a template, you may specify an index to
313              retrieve a specific value.  That index may also be a define-d
314              value.
315
316       -U name-pat, --undefine=name-pat
317              definition list removal pattern.  This option may appear an
318              unlimited number of times.  This option may not be preset with
319              environment variables or in initialization (rc) files.
320
321              Just like 'C', AutoGen uses #ifdef/#ifndef preprocessing direc‐
322              tives.  This option will cause the matching names to be removed
323              from the list of defined values.
324
325       -?, --help
326              Display usage information and exit.
327
328       -!, --more-help
329              Extended usage information passed thru pager.
330
331       -> [rcfile], --save-opts[=rcfile]
332              Save the option state to rcfile.  The default is the last con‐
333              figuration file listed in the OPTION PRESETS section, below.
334
335       -< rcfile, --load-opts=rcfile, --no-load-opts
336              Load options from rcfile.  The no-load-opts form will disable
337              the loading of earlier RC/INI files.  --no-load-opts is handled
338              early, out of order.
339
340       -v [{v|c|n}], --version[={v|c|n}]
341              Output version of program and exit.  The default mode is `v', a
342              simple version.  The `c' mode will print copyright information
343              and `n' will print the full copyright notice.
344

OPTION PRESETS

346       Any option that is not marked as not presettable may be preset by load‐
347       ing values from configuration ("RC" or ".INI") file(s) and values from
348       environment variables named:
349         AUTOGEN_<option-name> or AUTOGEN
350       The environmental presets take precedence (are processed later than)
351       the configuration files.  The homerc files are "$HOME", and ".".  If
352       any of these are directories, then the file .autogenrc is searched for
353       within those directories.
354

SEE ALSO

356       This program is documented more fully in the AutoGen Info system docu‐
357       mentation.
358
359

EXAMPLES

361           autogen -T man.tpl --base-name=autogen opts.def
362
363
364       This command produced this man page from the AutoGen option definition
365       file.  It overrides the template specified in opts.def (normally
366       options.tpl) and uses man.tpl.  It also overrides the base-name of the
367       output file, which is normally derived from the input definition file
368       name (viz. opts).
369

AUTHOR

371       Bruce Korb
372       Please send bug reports to:  autogen-users@lists.sourceforge.net
373
374
375       Released under the GNU General Public License.
376
377       This manual page was AutoGen-erated from the autogen option defini‐
378       tions.
379
380
381
382(GNU AutoGen 5.9.4)               2009-08-10                        AUTOGEN(1)
Impressum