Node:Invoking autom4te, Next:, Previous:M4 Quotation, Up:Programming in M4


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

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 (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. 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). 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 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.

See 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.