Merge branch 'maint' into yacc-work

* maint: (75 commits)
  test defs: function 'is_newest' now works also with directories
  refactor: new variable telling whether make is running in "dry mode"
  ...

2 files changed, 130 insertions, 84 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index f4f76c660..655673b49 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -2,7 +2,8 @@
 
 ## Makefile for Automake.
 
-# Copyright (C) 2003, 2006, 2008, 2009  Free Software Foundation, Inc.
+# Copyright (C) 2003, 2006, 2008, 2009, 2012 Free Software Foundation,
+# Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -70,7 +71,8 @@ dist_doc_DATA = $(srcdir)/amhello-1.0.tar.gz
 # aclocal-$(APIVERSION) and automake-$(APIVERSION) are generated by
 # configure in tests/.
 $(srcdir)/amhello-1.0.tar.gz: $(amhello_sources) $(top_srcdir)/configure.ac
-	PATH="`pwd`/../tests$(PATH_SEPARATOR)$$PATH" && \
+	$(AM_V_GEN)abs_top_builddir=`cd '$(top_builddir)' && pwd` && \
+	PATH="$$abs_top_builddir/tests$(PATH_SEPARATOR)$$PATH" && \
 	export PATH && \
 	cd $(srcdir)/amhello && \
 	ACLOCAL=aclocal-$(APIVERSION) && export ACLOCAL && \
diff --git a/doc/automake.texi b/doc/automake.texi
index fe94f08c7..e84df4a06 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -24,7 +24,7 @@ This manual is for GNU Automake (version @value{VERSION},
 Makefiles from template files.
 
 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software
+2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software
 Foundation, Inc.
 
 @quotation
@@ -45,8 +45,8 @@ section entitled ``GNU Free Documentation License.''
 
 @dircategory Individual utilities
 @direntry
-* aclocal-invocation: (automake)Invoking aclocal.    Generating aclocal.m4.
-* automake-invocation: (automake)Invoking Automake.  Generating Makefile.in.
+* aclocal-invocation: (automake)aclocal Invocation.   Generating aclocal.m4.
+* automake-invocation: (automake)automake Invocation. Generating Makefile.in.
 @end direntry
 
 @titlepage
@@ -99,7 +99,7 @@ section entitled ``GNU Free Documentation License.''
 * Autotools Introduction::      An Introduction to the Autotools
 * Generalities::                General ideas
 * Examples::                    Some example packages
-* Invoking Automake::           Creating a Makefile.in
+* automake Invocation::         Creating a Makefile.in
 * configure::                   Scanning configure.ac, using aclocal
 * Directories::                 Declaring subdirectories
 * Programs::                    Building programs and libraries
@@ -178,7 +178,7 @@ Scanning @file{configure.ac}, using @command{aclocal}
 
 * Requirements::                Configuration requirements
 * Optional::                    Other things Automake recognizes
-* Invoking aclocal::            Auto-generating aclocal.m4
+* aclocal Invocation::          Auto-generating aclocal.m4
 * Macros::                      Autoconf macros supplied with Automake
 
 Auto-generating aclocal.m4
@@ -323,7 +323,7 @@ Miscellaneous Rules
 
 * Tags::                        Interfacing to etags and mkid
 * Suffixes::                    Handling new file extensions
-* Multilibs::                   Support for multilibs.
+* Multilibs::                   Support for multilibs (deprecated, soon to be removed).
 
 Conditionals
 
@@ -2270,8 +2270,11 @@ release.
 
 @item config-ml.in
 This file is not a program, it is a @file{configure} fragment used for
-multilib support (@pxref{Multilibs}).  This file is maintained in the
-GCC tree at @url{http://gcc.gnu.org/svn.html}.
+multilib support (@pxref{Multilibs}).  Since the Automake multilib
+support has been @emph{deprecated} and targeted for removal, this
+file is going to be @emph{removed from the Automake core} in the next
+major release.  The master copy of this file is maintained in the GCC
+tree at @url{http://gcc.gnu.org/svn.html}.
 
 @item depcomp
 This program understands how to run a compiler so that it will
@@ -2312,8 +2315,11 @@ This is used to byte-compile Python scripts.
 @item symlink-tree
 This program duplicates a tree of directories, using symbolic links
 instead of copying files.  Such an operation is performed when building
-multilibs (@pxref{Multilibs}).  This file is maintained in the GCC
-tree at @url{http://gcc.gnu.org/svn.html}.
+multilibs (@pxref{Multilibs}).  Since the Automake multilib support has
+been @emph{deprecated} and targeted for removal, this file is going to
+be @emph{removed from the Automake core} in the next major release.
+The master copy of this file is maintained in the GCC tree at
+@url{http://gcc.gnu.org/svn.html}.
 
 @item texinfo.tex
 Not a program, this file is required for @samp{make dvi}, @samp{make
@@ -2492,13 +2498,17 @@ with different flags.  In this instance, the names of the object files
 would be chosen by automake; they would be @file{false-true.o} and
 @file{true-true.o}. (The name of the object files rarely matters.)
 
-
-@node Invoking Automake
+@node automake Invocation
 @chapter Creating a @file{Makefile.in}
+@c This node used to be named "Invoking automake".  This @anchor
+@c allows old links to still work.
+@anchor{Invoking automake}
 
 @cindex Multiple @file{configure.ac} files
 @cindex Invoking @command{automake}
 @cindex @command{automake}, invoking
+@cindex Invocation of @command{automake}
+@cindex @command{automake}, invocation
 
 To create all the @file{Makefile.in}s for a package, run the
 @command{automake} program in the top level directory, with no
@@ -2729,7 +2739,7 @@ easier.  These macros can automatically be put into your
 @menu
 * Requirements::                Configuration requirements
 * Optional::                    Other things Automake recognizes
-* Invoking aclocal::            Auto-generating aclocal.m4
+* aclocal Invocation::          Auto-generating aclocal.m4
 * Macros::                      Autoconf macros supplied with Automake
 @end menu
 
@@ -3099,16 +3109,19 @@ appear as dependencies in @file{Makefile} rules.
 
 @code{m4_include} is seldom used by @file{configure.ac} authors, but
 can appear in @file{aclocal.m4} when @command{aclocal} detects that
-some required macros come from files local to your package (as opposed
-to macros installed in a system-wide directory, @pxref{Invoking
-aclocal}).
+some required macros come from files local to your package (as opposed to
+macros installed in a system-wide directory, @pxref{aclocal Invocation}).
 
 @end ftable
 
-
-@node Invoking aclocal
+@node aclocal Invocation
 @section Auto-generating aclocal.m4
+@c This node used to be named "Invoking automake".  This @anchor
+@c allows old links to still work.
+@anchor{Invoking aclocal}
 
+@cindex Invocation of @command{aclocal}
+@cindex @command{aclocal}, Invocation
 @cindex Invoking @command{aclocal}
 @cindex @command{aclocal}, Invoking
 
@@ -3291,7 +3304,7 @@ All warnings are output by default.
 
 @vindex WARNINGS
 The environment variable @env{WARNINGS} is honored in the same
-way as it is for @command{automake} (@pxref{Invoking Automake}).
+way as it is for @command{automake} (@pxref{automake Invocation}).
 
 @end table
 
@@ -3897,12 +3910,18 @@ Automake ships with several Autoconf macros that you can use from your
 
 @item AM_ENABLE_MULTILIB
 @acindex AM_ENABLE_MULTILIB
-This is used when a ``multilib'' library is being built.  The first
-optional argument is the name of the @file{Makefile} being generated; it
-defaults to @samp{Makefile}.  The second optional argument is used to find
-the top source directory; it defaults to the empty string (generally
-this should not be used unless you are familiar with the internals).
-@xref{Multilibs}.
+
+This is used when a ``multilib'' library is being built.  Please be
+aware that multilib support @emph{will be removed} from the Automake
+core in the next major release, and then @emph{this macro will go away
+as well} (even if a ``frozen'' version of will remain available in the
+@file{contrib/} directory of the Automake distribution).
+
+The first optional argument is the name of the @file{Makefile} being
+generated; it defaults to @samp{Makefile}.  The second optional argument
+is used to find the top source directory; it defaults to the empty
+string (generally this should not be used unless you are familiar with
+the internals).  @xref{Multilibs}.
 
 @item AM_INIT_AUTOMAKE([OPTIONS])
 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
@@ -4815,11 +4834,12 @@ this purpose.
 
 @cindex @code{_DEPENDENCIES}, defined
 @vindex maude_DEPENDENCIES
+@vindex EXTRA_maude_DEPENDENCIES
 It is also occasionally useful to have a program depend on some other
 target that is not actually part of that program.  This can be done
-using the @code{@var{prog}_DEPENDENCIES} variable.  Each program
-depends on the contents of such a variable, but no further
-interpretation is done.
+using either the @code{@var{prog}_DEPENDENCIES} or the
+@code{EXTRA_@var{prog}_DEPENDENCIES} variable.  Each program depends on
+the contents both variables, but no further interpretation is done.
 
 Since these dependencies are associated to the link rule used to
 create the programs they should normally list files used by the link
@@ -4842,6 +4862,10 @@ generated.
 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
 may be used.
 
+The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
+you merely want to augment the @command{automake}-generated
+@code{@var{prog}_DEPENDENCIES} rather than replacing it.
+
 @cindex @code{LDADD} and @option{-l}
 @cindex @option{-l} and @code{LDADD}
 We recommend that you avoid using @option{-l} options in @code{LDADD}
@@ -5716,6 +5740,7 @@ option, so they should not be mode-specific options (those belong to
 the compiler or linker flags).  @xref{Libtool Flags}.
 
 @item maude_DEPENDENCIES
+@itemx EXTRA_maude_DEPENDENCIES
 It is also occasionally useful to have a target (program or library)
 depend on some other file that is not actually part of that target.
 This can be done using the @code{_DEPENDENCIES} variable.  Each
@@ -5746,6 +5771,10 @@ compilation using an @code{AC_SUBST} variable that contains a list of
 objects.  @xref{Conditional Sources}, and @ref{Conditional Libtool
 Sources}.
 
+The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
+you merely want to augment the @command{automake}-generated
+@code{_DEPENDENCIES} variable rather than replacing it.
+
 @item maude_LINK
 You can override the linker on a per-program basis.  By default the
 linker is chosen according to the languages used by the program.  For
@@ -5956,9 +5985,10 @@ However there is no need to list the corresponding sources in
 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
 dependencies, and it will discover the list of corresponding source
 files automatically (by tracing the invocations of the
-@code{AC_LIBSOURCE} Autoconf macros).  However, if you have already
-defined @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then
-you have to add these variables manually.
+@code{AC_LIBSOURCE} Autoconf macros).  If you have already defined
+@samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
+either need to add these variables manually, or use
+@samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
 
 These variables are usually used to build a portability library that
 is linked with all the programs of the project.  We now review a
@@ -7085,11 +7115,12 @@ prefix as with other primaries.
 @vindex sbin_SCRIPTS
 @vindex libexec_SCRIPTS
 @vindex pkgdata_SCRIPTS
+@vindex pkglibexec_SCRIPTS
 @vindex noinst_SCRIPTS
 @vindex check_SCRIPTS
 
 Scripts can be installed in @code{bindir}, @code{sbindir},
-@code{libexecdir}, or @code{pkgdatadir}.
+@code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
 
 Scripts that need not be installed can be listed in
 @code{noinst_SCRIPTS}, and among them, those which are needed only by
@@ -8663,11 +8694,16 @@ environment variable.  For example, @samp{make dist-bzip2 BZIP2=-7}.
 Generate a gzip tar archive of the distribution.
 @trindex dist-gzip
 
-@item @code{dist-lzma}
-Generate an @samp{lzma} tar archive of the distribution.  @command{lzma}
+@item @code{dist-lzip}
+Generate a @samp{lzip} tar archive of the distribution.  @command{lzip}
 archives are frequently smaller than @command{bzip2}-compressed archives.
+@trindex dist-lzip
+
+@item @code{dist-lzma}
+Generate an @samp{lzma} tar archive of the distribution.
 The @samp{lzma} format is obsolete, you should use the @samp{xz} format
-instead.
+instead. @emph{Support for @samp{lzma}-compressed archives will be
+removed in the next major Automake release.}
 @trindex dist-lzma
 
 @item @code{dist-shar}
@@ -8809,17 +8845,17 @@ by the tests, not the tests themselves.  Of course you can set
 @section Simple Tests using @samp{parallel-tests}
 @cindex @option{parallel-tests}, Using
 
-The option @option{parallel-tests} (@pxref{Options}) enables a test
-suite driver that is mostly compatible to the simple test driver described
-in the previous section, but provides a few more features and slightly different
-semantics.  It features concurrent execution of tests with @code{make -j},
-allows to specify inter-test dependencies, lazy reruns of tests that
-have not completed in a prior run, summary and verbose output in
-@samp{RST} (reStructuredText) and @samp{HTML} format, and hard errors
-for exceptional failures.  Similar to the simple test driver,
-@code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS}, @code{XFAIL_TESTS}, and
-the @code{check_*} variables are honored, and the environment variable
-@env{srcdir} is set during test execution.
+The option @option{parallel-tests} (@pxref{Options}) enables a test suite
+driver that is mostly compatible to the simple test driver described in
+the previous section, but provides a few more features and slightly
+different semantics.  It features concurrent execution of tests with
+@code{make -j} and automatic collection of the test scripts output and
+summary thereof in @file{.log} files, and allows to specify inter-test
+dependencies, lazy reruns of tests that have not completed in a prior
+run, and hard errors for exceptional failures.  Similar to the simple
+test driver, @code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS},
+@code{XFAIL_TESTS}, and the @code{check_*} variables are honored,
+and the environment variable @env{srcdir} is set during test execution.
 
 This test driver is still experimental and may undergo changes in order
 to satisfy additional portability requirements.
@@ -8898,16 +8934,13 @@ intermingled output.  The output from failed tests is collected in the
 file is output after the summary.  For best results, the tests should be
 verbose by default now.
 
-@trindex mostlyclean
 @trindex check-html
 @vindex RST2HTML
 @vindex TEST_SUITE_HTML
-With @code{make check-html}, the log files may be converted from RST
-(reStructuredText, see @uref{http://docutils.sourceforge.net/@/rst.html})
-to HTML using @samp{RST2HTML}, which defaults to @command{rst2html} or
-@command{rst2html.py}.  The variable @samp{TEST_SUITE_HTML} contains the
-set of converted log files.  The log and HTML files are removed upon
-@code{make mostlyclean}.
+Previous versions of automake used to provide a @code{check-html} target
+to convert the log files to HTML.  This feature is now deprecated, and
+@emph{will be removed} in the next major Automake release, so don't rely
+on it anymore.
 
 @vindex DISABLE_HARD_ERRORS
 @cindex Exit status 99, special interpretation
@@ -8982,13 +9015,10 @@ env RECHECK_LOGS= make -e check
 
 @item
 @trindex recheck
-@trindex recheck-html
 You can ensure that all tests are rerun which have failed or passed
 unexpectedly, by running @code{make recheck} in the test directory.
 This convenience target will set @code{RECHECK_LOGS} appropriately
-before invoking the main test driver.  The @code{recheck-html} target
-does the same as @code{recheck} but again converts the resulting log
-file in HTML format, like the @code{check-html} target.
+before invoking the main test driver.
 @end itemize
 
 In order to guarantee an ordering between tests even with @code{make
@@ -9275,6 +9305,12 @@ Cause @command{dejagnu}-specific rules to be generated.  @xref{DejaGnu Tests}.
 Hook @code{dist-bzip2} to @code{dist}.
 @trindex dist-bzip2
 
+@item @option{dist-lzip}
+@cindex Option, @option{dist-lzip}
+@opindex dist-lzip
+Hook @code{dist-lzip} to @code{dist}.
+@trindex dist-lzip
+
 @item @option{dist-lzma}
 @cindex Option, @option{dist-lzma}
 @opindex dist-lzma
@@ -9475,7 +9511,8 @@ In order to use this option with C sources, you should add
 These three mutually exclusive options select the tar format to use
 when generating tarballs with @samp{make dist}.  (The tar file created
 is then compressed according to the set of @option{no-dist-gzip},
-@option{dist-bzip2}, @option{dist-xz} and @option{dist-tarZ} options in use.)
+@option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
+@option{dist-tarZ} options in use.)
 
 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
 (@pxref{Macros}) because they can require additional configure checks.
@@ -9527,7 +9564,7 @@ will be suppressed.
 @cindex Option, @option{-W@var{category}}
 @cindex Option, @option{--warnings=@var{category}}
 These options behave exactly like their command-line counterpart
-(@pxref{Invoking Automake}).  This allows you to enable or disable some
+(@pxref{automake Invocation}).  This allows you to enable or disable some
 warning categories on a per-file basis.  You can also setup some warnings
 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
 in your @file{configure.ac}.
@@ -9547,9 +9584,9 @@ the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
 There are a few rules and variables that didn't fit anywhere else.
 
 @menu
-* Tags::                        Interfacing to etags and mkid
-* Suffixes::                    Handling new file extensions
-* Multilibs::                   Support for multilibs.
+* Tags::        Interfacing to etags and mkid
+* Suffixes::    Handling new file extensions
+* Multilibs::   Support for multilibs (deprecated, soon to be removed).
 @end menu
 
 
@@ -9670,19 +9707,21 @@ Automake generate the suffix list for @code{.SUFFIXES}.  Any given
 by Automake generated suffixes not already in the list.
 
 @node Multilibs
-@section Support for Multilibs
+@section Support for Multilibs (deprecated, soon to be removed).
+
+Automake used to support an obscure feature called multilibs.  @emph{This
+feature is now deprecated, and will be removed in the next major Automake
+version}.  Still, its implementation will remain available in the
+@file{contrib/} directory of the Automake distribution, so it should be
+very easy for motivated users to continue to use it in their projects,
+if they really need to.
 
-Automake has support for an obscure feature called multilibs.  A
-@dfn{multilib} is a library that is built for multiple different ABIs
+A @dfn{multilib} is a library that is built for multiple different ABIs
 at a single time; each time the library is built with a different target
 flag combination.  This is only useful when the library is intended to
 be cross-compiled, and it is almost exclusively used for compiler
 support libraries.
 
-The multilib support is still experimental.  Only use it if you are
-familiar with multilibs and can debug problems you might encounter.
-
-
 @node Include
 @chapter Include
 
@@ -10135,18 +10174,23 @@ For portability to different @command{make} implementations, package authors
 are advised to not set the variable @code{V} inside the @file{Makefile.am}
 file, to allow the user to override the value for subdirectories as well.
 
-The current implementation of this feature relies on a non-POSIX, but in
-practice rather widely supported @file{Makefile} construct of nested
-variable expansion @samp{$(@var{var1}$(V))}.  Do not use the
-@option{silent-rules} option if your package needs to build with
-@command{make} implementations that do not support it.  The
-@option{silent-rules} option turns off warnings about recursive variable
-expansion, which are in turn enabled by @option{-Wportability}
-(@pxref{Invoking Automake}).
+The current implementation of this feature normally uses nested
+variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
+that is not required by POSIX 2008 but is widely supported in
+practice.  The @option{silent-rules} option thus turns off warnings
+about recursive variable expansion, which are in turn enabled by
+@option{-Wportability} (@pxref{automake Invocation}).  On the rare
+@command{make} implementations that do not support nested variable
+expansion, whether rules are silent is always determined at configure
+time, and cannot be overridden at make time.  Future versions of POSIX
+are likely to require nested variable expansion, so this minor
+limitation should go away with time.
 
 @vindex @code{AM_V_GEN}
 @vindex @code{AM_V_at}
 @vindex @code{AM_DEFAULT_VERBOSITY}
+@vindex @code{AM_V}
+@vindex @code{AM_DEFAULT_V}
 To extend the silent mode to your own rules, you have two choices:
 
 @itemize @bullet
@@ -10162,8 +10206,8 @@ The following snippet shows how you would define your own equivalent of
 @code{AM_V_GEN}:
 
 @example
-pkg_verbose = $(pkg_verbose_$(V))
-pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
+pkg_verbose = $(pkg_verbose_@@AM_V@@)
+pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
 pkg_verbose_0 = @@echo PKG-GEN $@@;
 
 foo: foo.in
@@ -10362,7 +10406,7 @@ These overriding semantics make it possible to fine tune some default
 settings of Automake, or replace some of its rules.  Overriding
 Automake rules is often inadvisable, particularly in the topmost
 directory of a package with subdirectories.  The @option{-Woverride}
-option (@pxref{Invoking Automake}) comes in handy to catch overridden
+option (@pxref{automake Invocation}) comes in handy to catch overridden
 definitions.
 
 Note that Automake does not make any distinction between rules with
@@ -10810,7 +10854,7 @@ autoreconf -vfi
 @end example
 
 The use of @option{--force-missing} ensures that auxiliary tools will be
-overridden by new versions (@pxref{Invoking Automake}).
+overridden by new versions (@pxref{automake Invocation}).
 
 It is important to regenerate all these files each time Automake is
 upgraded, even between bug fixes releases.  For instance, it is not
@@ -13534,4 +13578,4 @@ parentheses is the number of generated test cases.
 @c  LocalWords:  LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
 @c  LocalWords:  unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
 @c  LocalWords:  LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
-@c  LocalWords:  barexec Pinard's automatize initialize lzma xz
+@c  LocalWords:  barexec Pinard's automatize initialize lzip lzma xz