autoconf: autom4te Invocation
1
1 8.2.1 Invoking `autom4te'
1 -------------------------
1
1 The command line arguments are modeled after M4's:
1
1 autom4te OPTIONS FILES
1
1 where the FILES are directly passed to `m4'. By default, GNU M4 is
1 found during configuration, but the environment variable `M4' can be
1 set to tell `autom4te' where to look. In addition to the regular
11 expansion, it handles the replacement of the quadrigraphs (⇒
Quadrigraphs), and of `__oline__', the current line in the output.
1 It supports an extended syntax for the FILES:
1
1 `FILE.m4f'
1 This file is an M4 frozen file. Note that _all the previous files
1 are ignored_. See the option `--melt' for the rationale.
1
1 `FILE?'
1 If found in the library path, the FILE is included for expansion,
1 otherwise it is ignored instead of triggering a failure.
1
1
1 Of course, it supports the Autoconf common subset of options:
1
1 `--help'
1 `-h'
1 Print a summary of the command line options and exit.
1
1 `--version'
1 `-V'
1 Print the version number of Autoconf and exit.
1
1 `--verbose'
1 `-v'
1 Report processing steps.
1
1 `--debug'
1 `-d'
1 Don't remove the temporary files and be even more verbose.
1
1 `--include=DIR'
1 `-I DIR'
1 Also look for input files in DIR. Multiple invocations accumulate.
1
1 `--output=FILE'
1 `-o FILE'
1 Save output (script or trace) to FILE. The file `-' stands for
1 the standard output.
1
1
1 As an extension of `m4', it includes the following options:
1
1 `--warnings=CATEGORY'
1 `-W CATEGORY'
1 Report the warnings related to CATEGORY (which can actually be a
1 comma separated list). ⇒Reporting Messages, macro
1 `AC_DIAGNOSE', for a comprehensive list of categories. Special
1 values include:
1
1 `all'
1 report all the warnings
1
1 `none'
1 report none
1
1 `error'
1 treats warnings as errors
1
1 `no-CATEGORY'
1 disable warnings falling into CATEGORY
1
1 Warnings about `syntax' are enabled by default, and the environment
1 variable `WARNINGS', a comma separated list of categories, is
1 honored. `autom4te -W CATEGORY' actually behaves as if you had
1 run:
1
1 autom4te --warnings=syntax,$WARNINGS,CATEGORY
1
1 For example, if you want to disable defaults and `WARNINGS' of
1 `autom4te', but enable the warnings about obsolete constructs, you
1 would use `-W none,obsolete'.
1
1 `autom4te' displays a back trace for errors, but not for warnings;
1 if you want them, just pass `-W error'.
1
1 `--melt'
1 `-M'
1 Do not use frozen files. Any argument `FILE.m4f' is replaced by
1 `FILE.m4'. This helps tracing the macros which are executed only
1 when the files are frozen, typically `m4_define'. For instance,
1 running:
1
1 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
1
1 is roughly equivalent to running:
1
1 m4 1.m4 2.m4 3.m4 4.m4 input.m4
1
1 while
1
1 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
1
1 is equivalent to:
1
1 m4 --reload-state=4.m4f input.m4
1
1 `--freeze'
1 `-F'
1 Produce a frozen state file. `autom4te' freezing is stricter than
1 M4's: it must produce no warnings, and no output other than empty
1 lines (a line with white space is _not_ empty) and comments
1 (starting with `#'). Unlike `m4''s similarly-named option, this
1 option takes no argument:
1
1 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
1
1 corresponds to
1
1 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
1
1 `--mode=OCTAL-MODE'
1 `-m OCTAL-MODE'
1 Set the mode of the non-traces output to OCTAL-MODE; by default
1 `0666'.
1
1
1 As another additional feature over `m4', `autom4te' caches its
1 results. GNU M4 is able to produce a regular output and traces at the
1 same time. Traces are heavily used in the GNU Build System:
1 `autoheader' uses them to build `config.h.in', `autoreconf' to
1 determine what GNU Build System components are used, `automake' to
1 "parse" `configure.ac' etc. To avoid recomputation, traces are cached
1 while performing regular expansion, and conversely. This cache is
1 (actually, the caches are) stored in the directory `autom4te.cache'.
1 _It can safely be removed_ at any moment (especially if for some reason
1 `autom4te' considers it trashed).
1
1 `--cache=DIRECTORY'
1 `-C DIRECTORY'
1 Specify the name of the directory where the result should be
1 cached. Passing an empty value disables caching. Be sure to pass
1 a relative file name, as for the time being, global caches are not
1 supported.
1
1 `--no-cache'
1 Don't cache the results.
1
1 `--force'
1 `-f'
1 If a cache is used, consider it obsolete (but update it anyway).
1
1
1 Because traces are so important to the GNU Build System, `autom4te'
1 provides high level tracing features as compared to M4, and helps
1 exploiting the cache:
1
1 `--trace=MACRO[:FORMAT]'
1 `-t MACRO[:FORMAT]'
1 Trace the invocations of MACRO according to the FORMAT. Multiple
1 `--trace' arguments can be used to list several macros. Multiple
1 `--trace' arguments for a single macro are not cumulative;
1 instead, you should just make FORMAT as long as needed.
1
1 The FORMAT is a regular string, with newlines if desired, and
1 several special escape codes. It defaults to `$f:$l:$n:$%'. It
1 can use the following special escapes:
1
1 `$$'
1 The character `$'.
1
1 `$f'
1 The file name from which MACRO is called.
1
1 `$l'
1 The line number from which MACRO is called.
1
1 `$d'
1 The depth of the MACRO call. This is an M4 technical detail
1 that you probably don't want to know about.
1
1 `$n'
1 The name of the MACRO.
1
1 `$NUM'
1 The NUMth argument of the call to MACRO.
1
1 `$@'
1 `$SEP@'
1 `${SEPARATOR}@'
1 All the arguments passed to MACRO, separated by the character
1 SEP or the string SEPARATOR (`,' by default). Each argument
1 is quoted, i.e., enclosed in a pair of square brackets.
1
1 `$*'
1 `$SEP*'
1 `${SEPARATOR}*'
1 As above, but the arguments are not quoted.
1
1 `$%'
1 `$SEP%'
1 `${SEPARATOR}%'
1 As above, but the arguments are not quoted, all new line
1 characters in the arguments are smashed, and the default
1 separator is `:'.
1
1 The escape `$%' produces single-line trace outputs (unless
1 you put newlines in the `separator'), while `$@' and `$*' do
1 not.
1
1 ⇒autoconf Invocation, for examples of trace uses.
1
1 `--preselect=MACRO'
1 `-p MACRO'
1 Cache the traces of MACRO, but do not enable traces. This is
1 especially important to save CPU cycles in the future. For
1 instance, when invoked, `autoconf' preselects all the macros that
1 `autoheader', `automake', `autoreconf', etc., trace, so that
1 running `m4' is not needed to trace them: the cache suffices.
1 This results in a huge speed-up.
1
1
1 Finally, `autom4te' introduces the concept of "Autom4te libraries".
1 They consists in a powerful yet extremely simple feature: sets of
1 combined command line arguments:
1
1 `--language=LANGUAGE'
1 `-l LANGUAGE'
1 Use the LANGUAGE Autom4te library. Current languages include:
1
1 `M4sugar'
1 create M4sugar output.
1
1 `M4sh'
1 create M4sh executable shell scripts.
1
1 `Autotest'
1 create Autotest executable test suites.
1
1 `Autoconf-without-aclocal-m4'
1 create Autoconf executable configure scripts without reading
1 `aclocal.m4'.
1
1 `Autoconf'
1 create Autoconf executable configure scripts. This language
1 inherits all the characteristics of
1 `Autoconf-without-aclocal-m4' and additionally reads
1 `aclocal.m4'.
1
1 `--prepend-include=DIR'
1 `-B DIR'
1 Prepend directory DIR to the search path. This is used to include
1 the language-specific files before any third-party macros.
1
1
1 As an example, if Autoconf is installed in its default location,
1 `/usr/local', the command `autom4te -l m4sugar foo.m4' is strictly
1 equivalent to the command:
1
1 autom4te --prepend-include /usr/local/share/autoconf \
1 m4sugar/m4sugar.m4f --warnings syntax foo.m4
1
1 Recursive expansion applies here: the command `autom4te -l m4sh foo.m4'
1 is the same as `autom4te --language M4sugar m4sugar/m4sh.m4f foo.m4',
1 i.e.:
1
1 autom4te --prepend-include /usr/local/share/autoconf \
1 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
1
1 The definition of the languages is stored in `autom4te.cfg'.
1