8.2.1 Invoking autom4te

The command line arguments are modeled after M4's:

autom4te optionsfiles

where the files are directly passed to m4. By default,
GNU M4 is found during configuration, but the environment
variable
M4 can be set to tell autom4te where to look. In addition
to the regular expansion, it handles the replacement of the quadrigraphs
(see 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.

--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). See 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’ actually
behaves as if you had run:

autom4te --warnings=syntax,$WARNINGS,category

For example, if you want to disable defaults and WARNINGS
of autom4te, but 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.

--melt

-M

Do not use frozen files. Any argument file.m4f is
replaced by 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 space is not empty) and comments
(starting with ‘#’). Unlike m4's similarly-named option,
this option 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 avoid recomputation,
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 trashed).

--cache=directory

-C directory

Specify the name of the directory where the result should be cached.
Passing an empty value disables caching. Be sure to pass a relative
file name, as for the time being, global caches are not supported.

--no-cache

Don't cache the results.

--force

-f

If a cache is used, consider it obsolete (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 of 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 file name 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.

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