Document how to propogate variables to submakes.

On bug-gnulib, archived at
     http://permalink.gmane.org/gmane.comp.lib.gnulib.bugs/22132
Ralf Wildenhues taught me a bit about how Automake propagates
variables to submakes.  I thought that it would good to document
this in the Autoconf manual, which currently has no detail at
all.

* doc/autoconf.texi: Describe technique used by Automake to
propagate variables to submakes in more detail.

Signed-off-by: Eric Blake <eblake@redhat.com>

diff --git a/ChangeLog b/ChangeLog
index f8a248d90421374779d1a610da926bb345151530..c74488deb8738ed7ed15df0fc10df06ec3508654 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2010-06-22  Ben Pfaff  <blp@cs.stanford.edu>
+
+       Document how to propogate variables to submakes.
+       * doc/autoconf.texi: Describe technique used by Automake to
+       propagate variables to submakes in more detail.
+
 2010-06-22  Peter Johansson  <trojkan@gmail.com>  (tiny change)
 
        Be consistent in doc example.

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index da4fa27389095407ca335cf8f223ad1f75d78d0e..5e0d754d48741b180c4727af4de25c657f35b84e 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -18753,8 +18753,8 @@ environment contains some other macros usually defined by the
 makefile.  (See also the note about @code{make -e} and @code{SHELL}
 below.)
 
-Another way to propagate overrides to submakes is to do it
-manually, from your makefile:
+If you can foresee all macros that a user might want to override, then
+you can propagate them to submakes manually, from your makefile:
 
 @example
 foo = foo
@@ -18765,12 +18765,25 @@ two:
         @@echo $(foo)
 @end example
 
-You need to foresee all macros that a user might want to override if
-you do that.
+Another way to propagate a variable to submakes in a portable way is to
+expand an extra variable in every invocation of @samp{$(MAKE)} within
+your makefile:
 
-Makefiles generated by @command{automake} expand @code{$(AM_MAKEFLAGS)}
-on the command line of submakes, which can be used for propagated overrides
-(@pxref{Subdirectories, , Automake, automake, GNU Automake}).
+@example
+foo = foo
+one:
+        @@echo $(foo)
+        $(MAKE) $(SUBMAKEFLAGS) two
+two:
+        @@echo $(foo)
+@end example
+
+Users must be aware that this technique is in use to take advantage of
+it, e.g.@: with @code{make foo=bar SUBMAKEFLAGS='foo=bar'}, but it
+allows any macro to be overridden.  Makefiles generated by
+@command{automake} use this technique, expanding @code{$(AM_MAKEFLAGS)}
+on the command lines of submakes (@pxref{Subdirectories, , Automake,
+automake, GNU Automake}).
 
 @node The Make Macro MAKEFLAGS
 @section The Make Macro MAKEFLAGS