autom4te Invocation

Go forward to Customizing autom4te
Go up to Using autom4te
Go to the top op autoconf

Invoking `autom4te'

The command line arguments are 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:
     This file is an M4 frozen file.  Note that _all the previous files
     are ignored_.  See the option `--melt' for the rationale.
     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:
     Print a summary of the command line options and exit.
     Print the version number of Autoconf and exit.
     Report processing steps.
     Don't remove the temporary files and be even more verbose.
`-I DIR'
     Also look for input files in DIR.  Multiple invocations accumulate.
`-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:
     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:
          report all the warnings
          report none
          treats warnings as errors
          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
          [AC_RUN_IFELSE([AC_LANG_PROGRAM([exit (0)])])])



     you get:
          $ autom4te -l autoconf -Wcross
 warning: AC_RUN_IFELSE called without default \
          to allow cross compiling
          $ autom4te -l autoconf -Wcross,error -f
 error: AC_RUN_IFELSE called without default \
          to allow cross compiling
          acgeneral.m4:3044: AC_RUN_IFELSE is expanded from...
 INNER is expanded from...
 OUTER is expanded from...
 the top level
     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
          autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
     is equivalent to:
          m4 --reload-state=4.m4f input.m4
     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 whitespace 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
     Set the mode of the non-traces output to OCTAL-MODE; by default
   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 `', `autoreconf' to
determine what GNU Build System components are used, `automake' to
"parse" `' 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).
     Specify the name of the directory where the result should be
     cached.  Passing an empty value disables caching.  Be sure to pass
     a relative path name, as for the time being, global caches are not
     Don't cache the results.
     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 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 `$'.

          The filename from which MACRO is called.
          The line number from which MACRO is called.
          The depth of the MACRO call.  This is an M4 technical detail
          that you probably don't want to know about.
          The name of the MACRO.
          The NUMth argument of the call to MACRO.
          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.
          As above, but the arguments are not quoted.
          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
     *Note autoconf Invocation::, for examples of trace uses.
`-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:
     Use the LANGUAGE Autom4te library.  Current languages include:
          create M4sugar output.
          create M4sh executable shell scripts.
          create Autotest executable test suites.
          create Autoconf executable configure scripts.
          create Autoconf executable configure scripts without reading
`-B DIR'
     Prepend directory DIR to the search path.  This is used to include
     the language-specific files before any third-party macros.
   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 --prepend-include
/usr/local/share/autoconf m4sugar/m4sugar.m4f --warnings 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 --prepend-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'.