Merge branch 'maint' into msvc

2 files changed, 75 insertions, 53 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 bc19ad0b1..7421029dd 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
@@ -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
 
@@ -2278,8 +2278,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
@@ -2320,8 +2323,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
@@ -3921,12 +3927,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])
@@ -4849,11 +4861,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
@@ -4876,6 +4889,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}
@@ -5752,6 +5769,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
@@ -5782,6 +5800,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
@@ -5992,9 +6014,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
@@ -7117,11 +7140,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
@@ -8846,17 +8870,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.
@@ -8935,16 +8959,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
@@ -9019,13 +9040,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
@@ -9591,9 +9609,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
 
 
@@ -9714,19 +9732,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 has support for an obscure feature called multilibs.  A
-@dfn{multilib} is a library that is built for multiple different ABIs
+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.
+
+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