Merge branch 'maint'

[platform/upstream/automake.git] / doc / automake.texi

diff --git a/doc/automake.texi b/doc/automake.texi
index 6be7ac3..0cdeb7b 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -354,7 +354,7 @@ Miscellaneous Rules
 
 * Tags::                        Interfacing to cscope, etags and mkid
 * Suffixes::                    Handling new file extensions
-* Multilibs::                   Support for multilibs.
+* Multilibs::                   Support for multilibs (deprecated, soon to be removed).
 
 Conditionals
 
@@ -2305,8 +2305,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
@@ -2347,8 +2350,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 test-driver
 This implements the default test driver offered by the parallel
@@ -3954,12 +3960,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])
@@ -10332,7 +10344,7 @@ There are a few rules and variables that didn't fit anywhere else.
 @menu
 * Tags::                        Interfacing to cscope, etags and mkid
 * Suffixes::                    Handling new file extensions
-* Multilibs::                   Support for multilibs.
+* Multilibs::   Support for multilibs (deprecated, soon to be removed).
 @end menu
 
 
@@ -10461,19 +10473,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