01-invoking-autom4te.patch

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>
        
        * doc/autoconf.texi (Invoking autom4te): New.
        
Index: doc/autoconf.texi
--- doc/autoconf.texi Thu, 07 Mar 2002 20:54:01 +0100 akim
+++ doc/autoconf.texi Thu, 07 Mar 2002 20:58:00 +0100 akim
@@ -312,6 +312,7 @@ @node Top
 Programming in M4
 
 * M4 Quotation::                Protecting macros from unwanted expansion
+* Invoking autom4te::           The Autoconf executables backbone
 * Programming in M4sugar::      Convenient pure M4 macros
 * Programming in M4sh::         Common Shell Constructs
 
@@ -6368,6 +6369,7 @@ @node Programming in M4
 
 @menu
 * M4 Quotation::                Protecting macros from unwanted expansion
+* Invoking autom4te::           The Autoconf executables backbone
 * Programming in M4sugar::      Convenient pure M4 macros
 * Programming in M4sh::         Common Shell Constructs
 @end menu
@@ -6869,6 +6871,340 @@ @node Quotation Rule Of Thumb
 unexpanded macros.  The @command{autoconf} program checks for this problem
 by doing @samp{grep AC_ configure}.
 
address@hidden Invoking autom4te
address@hidden Invoking @command{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 @command{m4}:
address@hidden@footnote{
address@hidden
+Yet another great name for Lars J. Aas.
address@hidden
+}.
+
address@hidden should basically considered as a replacement of
address@hidden itself.  In particular, its handling of command line
+arguments is modeled after M4's:
+
address@hidden
+autom4te @var{options} @var{files}
address@hidden example
+
address@hidden
+where the @var{files} are directly passed to @command{m4}.  In addition
+to the regular expansion, it handles the replacement of the quadrigraphs
+(@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
+output.  It supports an extended syntax for the @var{files}:
+
address@hidden @file
address@hidden @var{file}.m4f
+This file is an M4 frozen file.  Note that @emph{all the previous files
+are ignored}.  See the option @option{--melt} for the rationale.
+
address@hidden @var{file}?
+If found in the library path, the @var{file} is included for expansion,
+otherwise it is ignored instead of triggering a failure.
address@hidden table
+
address@hidden 1
+
+Of course, it supports the Autoconf common subset of options:
+
address@hidden @option
address@hidden --help
address@hidden -h
+Print a summary of the command line options and exit.
+
address@hidden --version
address@hidden -V
+Print the version number of Autoconf and exit.
+
address@hidden --verbose
address@hidden -v
+Report processing steps.
+
address@hidden --debug
address@hidden -d
+Don't remove the temporary files and be even more verbose.
+
address@hidden address@hidden
address@hidden -I @var{dir}
+Also look for input files in @var{dir}.  Multiple invocations
+accumulate.  Contrary to M4 but in agreement with common sense,
+directories are browsed from last to first.
+
address@hidden address@hidden
address@hidden -o @var{file}
+Save output (script or trace) to @var{file}.  The file @option{-} stands
+for the standard output.
address@hidden table
+
address@hidden 1
+
+As an extension of @command{m4}, it includes the following options:
+
address@hidden @option
address@hidden address@hidden
address@hidden -W @var{category}
address@hidden WARNINGS
address@hidden FIXME: Point to the M4sugar macros, not Autoconf's.
+Report the warnings related to @var{category} (which can actually be a
+comma separated list).  @xref{Reporting Messages}, macro
address@hidden, for a comprehensive list of categories.  Special
+values include:
+
address@hidden @samp
address@hidden all
+report all the warnings
+
address@hidden none
+report none
+
address@hidden error
+treats warnings as errors
+
address@hidden address@hidden
+disable warnings falling into @var{category}
address@hidden table
+
+Warnings about @samp{syntax} are enabled by default, and the environment
+variable @code{WARNINGS}, a comma separated list of categories, is
+honored. @command{autom4te -W @var{category}} will actually
+behave as if you had run:
+
address@hidden
+autom4te --warnings=syntax,$WARNINGS,@var{category}
address@hidden example
+
address@hidden
+If you want to disable @command{autom4te}'s defaults and
address@hidden, but (for example) enable the warnings about obsolete
+constructs, you would use @option{-W none,obsolete}.
+
address@hidden Back trace
address@hidden Macro invocation stack
address@hidden displays a back trace for errors, but not for
+warnings; if you want them, just pass @option{-W error}.  For instance,
+on this @file{configure.ac}:
+
address@hidden
+AC_DEFUN([INNER],
+[AC_TRY_RUN([exit (0)])])
+
+AC_DEFUN([OUTER],
+[INNER])
+
+AC_INIT
+OUTER
address@hidden example
+
address@hidden
+you get:
+
address@hidden
+$ @kbd{autom4te -l autoconf -Wcross}
+configure.ac:8: warning: AC_TRY_RUN called without default \
+to allow cross compiling
+$ @kbd{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
address@hidden example
+
address@hidden --melt
address@hidden -m
+Do not use frozen files.  Any argument @address@hidden will be
+replaced with @address@hidden  This helps tracing the macros which
+are executed only when the files are frozen, typically
address@hidden  For instance, running:
+
address@hidden
+autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
address@hidden example
+
address@hidden
+is roughly equivalent to running:
+
address@hidden
+m4 1.m4 2.m4 3.m4 4.m4 input.m4
address@hidden example
+
address@hidden
+while
+
address@hidden
+autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
address@hidden example
+
address@hidden
+is equivalent to:
+
address@hidden
+m4 --reload-state=4.m4f input.m4
address@hidden example
+
address@hidden --freeze
address@hidden -f
+Produce a frozen state file.  @command{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 @emph{not} empty) and comments
+(starting with @samp{#}).  Please, note that contrary to @command{m4},
+this options takes no argument:
+
address@hidden
+autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
address@hidden example
+
address@hidden
+corresponds to
+
address@hidden
+m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
address@hidden example
+
address@hidden address@hidden
address@hidden -m @var{octal-mode}
+Set the mode of the non traces output to @var{octal-mode}.  By default,
address@hidden
address@hidden table
+
address@hidden 1
+
address@hidden @file{autom4te.cache}
+As another additional feature over @command{m4}, @command{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: @command{autoheader} uses them to build @file{config.h.in},
address@hidden to determine what GNU Build System components are
+used, @command{automake} to ``parse'' @file{configure.ac} etc.  To save
+the long runs of @command{m4}, traces are cached while performing
+regular expansion, and conversely.  This cache is (actually, the caches
+are) stored in the directory @file{autom4te.cache}.  @emph{It can safely
+be removed} at any moment (especially if for some reason
address@hidden considers it is trashed).
+
address@hidden @option
address@hidden --force
address@hidden -f
+Do not consider the cache (but update it anyway).
address@hidden table
+
address@hidden 1
+
+Because traces are so important to the GNU Build System,
address@hidden provides high level tracing features as compared to
+M4, and helps exploiting the cache:
+
address@hidden @option
address@hidden address@hidden:@var{format}]
address@hidden -t @var{macro}[:@var{format}]
+Trace the invocations to @var{macro} according to the @var{format}.
+Multiple @option{--trace} arguments can be used to list several macros.
+Multiple @option{--trace} arguments for a single macro are not
+cumulative; instead, you should just make @var{format} as long as
+needed.
+
+The @var{format} is a regular string, with newlines if desired, and
+several special escape codes.  It defaults to @samp{$f:$l:$n:$%}. It can
+use the following special escapes:
+
address@hidden @samp
address@hidden $$
+The character @samp{$}.
+
address@hidden $f
+The filename from which @var{macro} is called.
+
address@hidden $l
+The line number from which @var{macro} is called.
+
address@hidden $d
+The depth of the @var{macro} call.  This is an M4 technical detail that
+you probably don't want to know about.
+
address@hidden $n
+The name of the @var{macro}.
+
address@hidden address@hidden
+The @var{num}th argument of the call to @var{macro}.
+
address@hidden $@@
address@hidden address@hidden@@
address@hidden address@hidden@address@hidden@@
+All the arguments passed to @var{macro}, separated by the character
address@hidden or the string @var{separator} (@samp{,} by default).  Each
+argument is quoted, i.e. enclosed in a pair of square brackets.
+
address@hidden $*
address@hidden address@hidden
address@hidden address@hidden@address@hidden
+As above, but the arguments are not quoted.
+
address@hidden $%
address@hidden address@hidden
address@hidden address@hidden@address@hidden
+As above, but the arguments are not quoted, all new line characters in
+the arguments are smashed, and the default separator is @samp{:}.
+
+The escape @samp{$%} produces single-line trace outputs (unless you put
+newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
+not.
address@hidden table
+
address@hidden Invocation}, for examples of trace uses.
+
address@hidden address@hidden
address@hidden -p @var{macro}
+Cache the traces of @var{macro}, but do not enable traces.  This is
+especially important to save cpu cycles in the future.  For instance,
+when invoked, @command{autoconf} preselects all the macros that
address@hidden, @code{automake}, @code{autoreconf} etc. will
+trace, so that running @command{m4} is not needed to trace them: the
+cache suffices.  This results in a huge speed-up.
address@hidden table
+
address@hidden 1
+
address@hidden Autom4te Library
+Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
+libraries}.  They consists in a powerful yet extremely simple feature:
+sets of combined command line arguments:
+
address@hidden @option
address@hidden address@hidden
address@hidden -l address@hidden
+Use the @var{language} Autom4te library.  Current languages include:
+
address@hidden @code
address@hidden M4sugar
+create M4sugar output.
+
address@hidden M4sh
+create M4sh executable shell scripts.
+
address@hidden Autotest
+create Autotest executable test suites.
+
address@hidden Autoconf
+create Autoconf executable configure scripts.
address@hidden table
address@hidden table
+
address@hidden @file{autom4te.cfg}
+As an example, if Autoconf is installed in its default location,
address@hidden/usr/local}, running @samp{autom4te -l m4sugar foo.m4} is strictly
+equivalent to running @samp{autom4te --include /usr/local/share/autoconf
+m4sugar/m4sugar.m4f --warning syntax foo.m4}.  Recursive expansion
+applies: running @samp{autom4te -l m4sh foo.m4}, is the same as
address@hidden --language M4sugar m4sugar/m4sh.m4f foo.m4}, i.e.,
address@hidden --include /usr/local/share/autoconf m4sugar/m4sugar.m4f
+m4sugar/m4sh.m4f --mode 777 foo.m4}.  The definition of the languages is
+stored in @file{autom4te.cfg}.
+
 
 @node Programming in M4sugar
 @section Programming in M4sugar
@@ -11889,18 +12225,10 @@ @node testsuite Scripts
 
 Generating testing or validation suites using Autotest is rather easy.
 The whole validation suite is held in a file to be processed through
address@hidden@address@hidden
address@hidden
address@hidden @command{autom4te}
-It is on purpose that we don't document @command{autom4te} which is yet
-another forthcoming Autoconf feature: it is being developed and
-polished.  It will be documented when ready for wide spread use.  Do not
-use it without at least being member of the Autoconf mailing lists.
address@hidden
-}, itself using GNU @code{m4} under the scene, to produce a stand-alone
-Bourne shell script which then gets distributed.  Neither
address@hidden nor GNU @code{m4} are not needed anymore at the
-installer end.
address@hidden, itself using GNU @code{m4} under the scene, to
+produce a stand-alone Bourne shell script which then gets distributed.
+Neither @command{autom4te} nor GNU @code{m4} are not needed anymore at
+the installer end.
 
 @cindex test group
 Each test of the validation suite should be part of some test group.  A
Index: lib/autom4te.in
--- lib/autom4te.in Wed, 30 Jan 2002 22:24:26 +0100 akim
+++ lib/autom4te.in Thu, 07 Mar 2002 21:00:26 +0100 akim
@@ -1,4 +1,4 @@
-# Definition of macro sets.                              -*- Makefile -*-
+# Definition of Autom4te option sets.                     -*- Makefile -*-
 #
 # Copyright 2001, 2002 Free Software Foundation, Inc.
 #
@@ -126,8 +126,6 @@ end-language: "Autoscan-preselections"
 ## ---------- ##
 
 begin-language: "Autoconf"
-# patterns: "*.ac"
-# patterns: "configure.in"
 args: --include @datadir@
 args: autoconf/autoconf.m4f
 args: acsite.m4?
@@ -147,7 +145,6 @@ end-language: "Autoconf"
 ## -------- ##
 
 begin-language: "Autotest"
-# patterns: *.at
 args: --include @datadir@
 args: autotest/autotest.m4f
 args: package.m4?
@@ -162,7 +159,6 @@ end-language: "Autotest"
 ## ---- ##
 
 begin-language: "M4sh"
-# patterns: *.as
 args: --include @datadir@
 args: m4sugar/m4sh.m4f
 args: --mode 777
@@ -176,7 +172,6 @@ end-language: "M4sh"
 ## ------- ##
 
 begin-language: "M4sugar"
-# patterns: *.msh
 args: --include @datadir@
 args: m4sugar/m4sugar.m4f
 args: --warning syntax