GNU Info
(autoconf.info)Invoking autom4te
Invoking `autom4te'
===================
The Autoconf suite, including M4sugar, M4sh, and Autotest in
addition to Autoconf per se, heavily rely on M4. All these different
uses revealed common needs factored into a layer over `m4':
`autom4te'(1).
`autom4te' should basically considered as a replacement of `m4'
itself. In particular, its handling of command line arguments is
modeled after M4's:
autom4te OPTIONS FILES
where the FILES are directly passed to `m4'. In addition to the
regular expansion, it handles the replacement of the quadrigraphs
(Note: Quadrigraphs), and of `__oline__', the current line in the
output. It supports an extended syntax for the FILES:
`FILE.m4f'
This file is an M4 frozen file. Note that _all the previous files
are ignored_. See the option `--melt' for the rationale.
`FILE?'
If found in the library path, the FILE is included for expansion,
otherwise it is ignored instead of triggering a failure.
Of course, it supports the Autoconf common subset of options:
`--help'
`-h'
Print a summary of the command line options and exit.
`--version'
`-V'
Print the version number of Autoconf and exit.
`--verbose'
`-v'
Report processing steps.
`--debug'
`-d'
Don't remove the temporary files and be even more verbose.
`--include=DIR'
`-I DIR'
Also look for input files in DIR. Multiple invocations
accumulate. Contrary to M4 but in agreement with common sense,
directories are browsed from last to first.
`--output=FILE'
`-o FILE'
Save output (script or trace) to FILE. The file `-' stands for
the standard output.
As an extension of `m4', it includes the following options:
`--warnings=CATEGORY'
`-W CATEGORY'
Report the warnings related to CATEGORY (which can actually be a
comma separated list). Note: Reporting Messages, macro
`AC_DIAGNOSE', for a comprehensive list of categories. Special
values include:
`all'
report all the warnings
`none'
report none
`error'
treats warnings as errors
`no-CATEGORY'
disable warnings falling into CATEGORY
Warnings about `syntax' are enabled by default, and the environment
variable `WARNINGS', a comma separated list of categories, is
honored. `autom4te -W CATEGORY' will actually behave as if you had
run:
autom4te --warnings=syntax,$WARNINGS,CATEGORY
If you want to disable `autom4te''s defaults and `WARNINGS', but
(for example) enable the warnings about obsolete constructs, you
would use `-W none,obsolete'.
`autom4te' displays a back trace for errors, but not for warnings;
if you want them, just pass `-W error'. For instance, on this
`configure.ac':
AC_DEFUN([INNER],
[AC_TRY_RUN([exit (0)])])
AC_DEFUN([OUTER],
[INNER])
AC_INIT
OUTER
you get:
$ autom4te -l autoconf -Wcross
configure.ac:8: warning: AC_TRY_RUN called without default \
to allow cross compiling
$ autom4te -l autoconf -Wcross,error
configure.ac:8: error: AC_TRY_RUN called without default \
to allow cross compiling
acgeneral.m4:3044: AC_TRY_RUN is expanded from...
configure.ac:2: INNER is expanded from...
configure.ac:5: OUTER is expanded from...
configure.ac:8: the top level
`--melt'
`-m'
Do not use frozen files. Any argument `FILE.m4f' will be replaced
with `FILE.m4'. This helps tracing the macros which are executed
only when the files are frozen, typically `m4_define'. For
instance, running:
autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
is roughly equivalent to running:
m4 1.m4 2.m4 3.m4 4.m4 input.m4
while
autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
is equivalent to:
m4 --reload-state=4.m4f input.m4
`--freeze'
`-f'
Produce a frozen state file. `autom4te' freezing is stricter than
M4's: it must produce no warnings, and no output other than empty
lines (a line with white spaces is _not_ empty) and comments
(starting with `#'). Please, note that contrary to `m4', this
options takes no argument:
autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
corresponds to
m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
`--mode=OCTAL-MODE'
`-m OCTAL-MODE'
Set the mode of the non traces output to OCTAL-MODE. By default,
`0666'.
As another additional feature over `m4', `autom4te' caches its
results. GNU M4 is able to produce a regular output and traces at the
same time. Traces are heavily used in the GNU Build System:
`autoheader' uses them to build `config.h.in', `autoreconf' to
determine what GNU Build System components are used, `automake' to
"parse" `configure.ac' etc. To save the long runs of `m4', traces are
cached while performing regular expansion, and conversely. This cache
is (actually, the caches are) stored in the directory `autom4te.cache'.
_It can safely be removed_ at any moment (especially if for some reason
`autom4te' considers it is trashed).
`--force'
`-f'
Do not consider the cache (but update it anyway).
Because traces are so important to the GNU Build System, `autom4te'
provides high level tracing features as compared to M4, and helps
exploiting the cache:
`--trace=MACRO[:FORMAT]'
`-t MACRO[:FORMAT]'
Trace the invocations to MACRO according to the FORMAT. Multiple
`--trace' arguments can be used to list several macros. Multiple
`--trace' arguments for a single macro are not cumulative;
instead, you should just make FORMAT as long as needed.
The FORMAT is a regular string, with newlines if desired, and
several special escape codes. It defaults to `$f:$l:$n:$%'. It can
use the following special escapes:
`$$'
The character `$'.
`$f'
The filename from which MACRO is called.
`$l'
The line number from which MACRO is called.
`$d'
The depth of the MACRO call. This is an M4 technical detail
that you probably don't want to know about.
`$n'
The name of the MACRO.
`$NUM'
The NUMth argument of the call to MACRO.
`$@'
`$SEP@'
`${SEPARATOR}@'
All the arguments passed to MACRO, separated by the character
SEP or the string SEPARATOR (`,' by default). Each argument
is quoted, i.e. enclosed in a pair of square brackets.
`$*'
`$SEP*'
`${SEPARATOR}*'
As above, but the arguments are not quoted.
`$%'
`$SEP%'
`${SEPARATOR}%'
As above, but the arguments are not quoted, all new line
characters in the arguments are smashed, and the default
separator is `:'.
The escape `$%' produces single-line trace outputs (unless
you put newlines in the `separator'), while `$@' and `$*' do
not.
Note: autoconf Invocation, for examples of trace uses.
`--preselect=MACRO'
`-p MACRO'
Cache the traces of MACRO, but do not enable traces. This is
especially important to save cpu cycles in the future. For
instance, when invoked, `autoconf' preselects all the macros that
`autoheader', `automake', `autoreconf' etc. will trace, so that
running `m4' is not needed to trace them: the cache suffices.
This results in a huge speed-up.
Finally, `autom4te' introduces the concept of "Autom4te libraries".
They consists in a powerful yet extremely simple feature: sets of
combined command line arguments:
`--language=LANGUAGE'
`-l =LANGUAGE'
Use the LANGUAGE Autom4te library. Current languages include:
`M4sugar'
create M4sugar output.
`M4sh'
create M4sh executable shell scripts.
`Autotest'
create Autotest executable test suites.
`Autoconf'
create Autoconf executable configure scripts.
As an example, if Autoconf is installed in its default location,
`/usr/local', running `autom4te -l m4sugar foo.m4' is strictly
equivalent to running `autom4te --include /usr/local/share/autoconf
m4sugar/m4sugar.m4f --warning syntax foo.m4'. Recursive expansion
applies: running `autom4te -l m4sh foo.m4', is the same as `autom4te
--language M4sugar m4sugar/m4sh.m4f foo.m4', i.e., `autom4te --include
/usr/local/share/autoconf m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode
777 foo.m4'. The definition of the languages is stored in
`autom4te.cfg'.
---------- Footnotes ----------
(1) Yet another great name for Lars J. Aas.
automatically generated by info2www version 1.2.2.9