multilib: deprecate, will be moved to contrib

As of 2012-01-17, according to Google codesarch, almost no active
package is using the 'multilib' feature offered by automake.

The only major exception seems to be GCC...  But on a closer look,
it become clear that GCC basically carries its own version of
multilib support.  In fact, Automake syncs its 'config-ml.in' and
'symlink-tree' scripts from GCC; and the GCC repository contains a
version of the 'multi.m4' file that is *more* updated than the one
in the automake repository (the former having being modified the
last time in 2008, the latter only in 2006).

The 'multilib' feature was anyway hardly documented at all, only
being briefly cited in the manual as an "obscure feature", "still
experimental", that was only for users "familiar with multilibs"
and which "can debug problems they might encounter".  We expect
such users to be motivated and knowledgeable enough to make the
minor adjustments required to start using the contrib version of
multilib, if they really need to.

* NEWS (Future backward incompatibility): Update.
* doc/automake.texi: Deprecate multilib support.  State that it
will be removed from automake core in the next major release.
* m4/multi.m4 (AM_ENABLE_MULTILIB): Deprecate.  If called, now
gives a proper warning in the 'obsolete' category (while still
retaining its former behaviour for the rest).
* tests/multilib.test: Update.
* contrib/multilib/multi.m4: New, verbatim copy of the earlier
version of multi.m4, without the new deprecation warning.
* Makefile.am (fetch): Don't sync the 'config-ml.in' file nor
the 'symlink-tree' script from GCC SVN repository anymore.
(FETCHFILES): Adjust.
(WGET_GCC): Remove, it's not needed anymore.

6 files changed, 132 insertions, 33 deletions

diff --git a/Makefile.am b/Makefile.am
index 06b33962b..ad4d372e1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -709,18 +709,15 @@ WGET_SV_CVS = $(WGET) http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/
 WGET_SV_GIT_CF = $(WGET) 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;hb=HEAD;f='
 WGET_SV_GIT_AC = $(WGET) 'http://git.savannah.gnu.org/gitweb/?p=autoconf.git;a=blob_plain;hb=HEAD;f='
 WGET_SV_GIT_GL = $(WGET) 'http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob_plain;hb=HEAD;f='
-WGET_GCC = $(WGET) 'http://gcc.gnu.org/viewcvs/*checkout*/trunk/'
 
 ## Files that we fetch and which we compare against.
 ## FIXME should be a lot more here
 FETCHFILES = \
 INSTALL \
-config-ml.in \
 config.guess \
 config.sub \
 gnupload \
 gitlog-to-changelog \
-symlink-tree \
 texinfo.tex
 
 ## Fetch the latest versions of files we care about.
@@ -734,9 +731,7 @@ fetch:
 	$(WGET_SV_CVS)texinfo/texinfo/doc/texinfo.tex -O texinfo.tex && \
 	$(WGET_SV_GIT_GL)doc/INSTALL -O INSTALL && \
 	$(WGET_SV_GIT_GL)build-aux/gnupload -O gnupload && \
-	$(WGET_SV_GIT_GL)build-aux/gitlog-to-changelog -O gitlog-to-changelog && \
-	$(WGET_GCC)config-ml.in -O config-ml.in && \
-	$(WGET_GCC)symlink-tree -O symlink-tree)
+	$(WGET_SV_GIT_GL)build-aux/gitlog-to-changelog -O gitlog-to-changelog)
 ## Don't exit after test because we want to give as many errors as
 ## possible.
 	@stat=0; for file in $(FETCHFILES); do \
diff --git a/NEWS b/NEWS
index 172889cad..3ae660483 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,10 @@ New in 1.11.0a:
 
 * WARNING: Future backward-incompatibilities!
 
+  - The support for the "obscure" multilib feature has been deprecated,
+    and will be moved out of the automake core in the next major Automake
+    release (1.12).
+
   - The support for ".log -> .html" conversion and the check-html and
     recheck-html targets will be removed in the next major Automake
     release (1.12).
diff --git a/contrib/multilib/multi.m4 b/contrib/multilib/multi.m4
new file mode 100644
index 000000000..98417679f
--- /dev/null
+++ b/contrib/multilib/multi.m4
@@ -0,0 +1,65 @@
+##                                                          -*- Autoconf -*-
+# Copyright (C) 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006
+# Free Software Foundation, Inc.
+#
+# This file is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# serial 6
+
+# AM_ENABLE_MULTILIB([MAKEFILE], [REL-TO-TOP-SRCDIR])
+# ---------------------------------------------------
+# Add --enable-multilib to configure.
+AC_DEFUN([AM_ENABLE_MULTILIB],
+[# Default to --enable-multilib
+AC_ARG_ENABLE(multilib,
+[  --enable-multilib       build many library versions (default)],
+[case "$enableval" in
+  yes) multilib=yes ;;
+  no)  multilib=no ;;
+  *)   AC_MSG_ERROR([bad value $enableval for multilib option]) ;;
+ esac],
+	      [multilib=yes])
+
+# We may get other options which we leave undocumented:
+# --with-target-subdir, --with-multisrctop, --with-multisubdir
+# See config-ml.in if you want the gory details.
+
+if test "$srcdir" = "."; then
+  if test "$with_target_subdir" != "."; then
+    multi_basedir="$srcdir/$with_multisrctop../$2"
+  else
+    multi_basedir="$srcdir/$with_multisrctop$2"
+  fi
+else
+  multi_basedir="$srcdir/$2"
+fi
+AC_SUBST(multi_basedir)
+
+# Even if the default multilib is not a cross compilation,
+# it may be that some of the other multilibs are.
+if test $cross_compiling = no && test $multilib = yes \
+   && test "x${with_multisubdir}" != x ; then
+   cross_compiling=maybe
+fi
+
+AC_OUTPUT_COMMANDS([
+# Only add multilib support code if we just rebuilt the top-level
+# Makefile.
+case " $CONFIG_FILES " in
+ *" ]m4_default([$1],Makefile)[ "*)
+   ac_file=]m4_default([$1],Makefile)[ . ${multi_basedir}/config-ml.in
+   ;;
+esac],
+		   [
+srcdir="$srcdir"
+host="$host"
+target="$target"
+with_multisubdir="$with_multisubdir"
+with_multisrctop="$with_multisrctop"
+with_target_subdir="$with_target_subdir"
+ac_configure_args="${multilib_arg} ${ac_configure_args}"
+multi_basedir="$multi_basedir"
+CONFIG_SHELL=${CONFIG_SHELL-/bin/sh}
+CC="$CC"])])dnl
diff --git a/doc/automake.texi b/doc/automake.texi
index cb31053cd..fb0e5e715 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -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
@@ -3904,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])
@@ -9568,9 +9580,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
 
 
@@ -9691,19 +9703,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
 
diff --git a/m4/multi.m4 b/m4/multi.m4
index 98417679f..447591f9e 100644
--- a/m4/multi.m4
+++ b/m4/multi.m4
@@ -1,5 +1,5 @@
 ##                                                          -*- Autoconf -*-
-# Copyright (C) 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006
+# Copyright (C) 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006, 2012
 # Free Software Foundation, Inc.
 #
 # This file is free software; the Free Software Foundation
@@ -12,6 +12,9 @@
 # ---------------------------------------------------
 # Add --enable-multilib to configure.
 AC_DEFUN([AM_ENABLE_MULTILIB],
+[m4_warn([obsolete], [$0 will be removed from Automake core soon.
+Files implementing the "multilib" feature are (and will remain) available
+to the 'contrib/' directory in the Automake distribution.])]dnl
 [# Default to --enable-multilib
 AC_ARG_ENABLE(multilib,
 [  --enable-multilib       build many library versions (default)],
diff --git a/tests/multlib.test b/tests/multlib.test
index 3f88be30a..75ef952e3 100755
--- a/tests/multlib.test
+++ b/tests/multlib.test
@@ -1,5 +1,6 @@
 #! /bin/sh
-# Copyright (C) 2003, 2004, 2007, 2010 Free Software Foundation, Inc.
+# Copyright (C) 2003, 2004, 2007, 2010, 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
@@ -22,6 +23,23 @@ required='gcc GNUmake'
 
 set -e
 
+# Multilib support has been deprecated in the Automake core.
+
+cat >>configure.in <<'END'
+AM_ENABLE_MULTILIB([Makefile], [.])
+END
+
+$ACLOCAL
+$AUTOCONF -Wall -Werror 2>stderr && { cat stderr >&2; Exit 1; }
+cat stderr >&2
+grep '^configure\.in:4:.*AM_ENABLE_MULTILIB.* removed.* soon' stderr
+grep '"multilib".*feature' stderr
+grep 'contrib.* in the Automake distribution' stderr
+
+rm -rf autom4te*.cache aclocal.m4 configure
+
+# Functional tests now.
+
 cat >configure.in <<'END'
 AC_INIT([multlib], [1.0])
 AC_CONFIG_SRCDIR(libfoo/foo.c)
@@ -110,16 +128,16 @@ mkdir libbar/sub
 cp "$testsrcdir/../lib/config-ml.in" .
 cp "$testsrcdir/../lib/symlink-tree" .
 
-$ACLOCAL
-$AUTOCONF
+$ACLOCAL -Wno-obsolete
+$AUTOCONF -Werror -Wall -Wno-obsolete
 $AUTOMAKE --add-missing
 cd libfoo
 $ACLOCAL
-$AUTOCONF
+$AUTOCONF -Werror -Wall -Wno-obsolete
 $AUTOMAKE --add-missing
 cd ../libbar
 $ACLOCAL
-$AUTOCONF
+$AUTOCONF -Werror -Wall -Wno-obsolete
 $AUTOMAKE --add-missing
 cd ..