ACLOCAL_PATH

[Ralf Wildenhues]

This patch adds yet another method to add macro directories to search by
aclocal, by specifying the environment variable $ACLOCAL_PATH.

Rationale: First, from a user's POV, aclocal's death is still greatly
exaggerated.  Second, setups like the following are not uncommon: you
have Autoconf and Automake versions provided by the system, no control
over the system, but you have installed (below $HOME) a new version of
Libtool and would like its macros to be preferred over the system
installation's.  Or be able to switch quickly between two gettext
installations' macros.

Recommending ACLOCAL="aclocal -I $HOME/share/aclocal" can help, but
not all packages use autoreconf, and of those who do, some make use
of the fact that aclocal's first -I argument is special if a relative
path is given.  The recommendation breaks this.

So, to address above scenario, $ACLOCAL_PATH should override or prepend
to the system path, but not address user search paths, nor kill
functionality that typically ACLOCAL_AMFLAGS are used for.

Several more details probably need to be looked at for possible
interactions, so I ask for feedback.

This patch is what I have now.  OK for HEAD?  Also branch-1-10
(I don't have a strong feeling, leaning to a slight 'no')?

Cheers,
Ralf

        * aclocal.in (parse_arguments): Honor `$ACLOCAL_PATH'.
        * doc/automake.texi (Macro search path): Update.
        * NEWS: Update.
        * tests/acloca23.test: New test.
        * tests/Makefile.am: Update.
        Suggested by Harlan Stenn.

Index: NEWS
===================================================================
RCS file: /cvs/automake/automake/NEWS,v
retrieving revision 1.331
diff -u -r1.331 NEWS
--- NEWS        22 Jul 2007 08:48:17 -0000      1.331
+++ NEWS        15 Aug 2007 05:33:17 -0000
@@ -6,6 +6,9 @@
     (and new in Automake 1.10) is degraded to a warning.  This helps
     in the common case where the Autoconf versions used are compatible.
 
+  - The environment variable ACLOCAL_PATH is honored.  The colon-separated
+    list of directories is prepended to the system (third-party) aclocal path.
+
 * Change to Libtool support:
 
   - Libtool generic flags are now passed to the install and uninstall
Index: aclocal.in
===================================================================
RCS file: /cvs/automake/automake/aclocal.in,v
retrieving revision 1.143
diff -u -r1.143 aclocal.in
--- aclocal.in  7 Jul 2007 12:16:27 -0000       1.143
+++ aclocal.in  15 Aug 2007 05:33:18 -0000
@@ -53,8 +53,9 @@
 # user-supplied directories first, then the directory containing the
 # automake macros, and finally the system-wide directories for
 # third-party macro.  @user_includes can be augmented with -I.
-# @system_includes can be augmented with the `dirlist' file.  Also
-# --acdir will reset both @automake_includes and @system_includes.
+# @system_includes can be augmented with the `dirlist' file and with
+# ACLOCAL_PATH.  Also --acdir will reset both @automake_includes and
+# @system_includes.
 my @user_includes = ();
 my @automake_includes = ("@datadir@/aclocal-$APIVERSION");
 my @system_includes = ('@datadir@/aclocal');
@@ -1023,6 +1024,8 @@
          close (DIRLIST);
        }
     }
+    push @system_includes, (split ':', $ENV{'ACLOCAL_PATH'})
+       if defined $ENV{'ACLOCAL_PATH'};
 }
 
 ################################################################
Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.170
diff -u -r1.170 automake.texi
--- doc/automake.texi   22 Jul 2007 09:27:37 -0000      1.170
+++ doc/automake.texi   15 Aug 2007 05:33:27 -0000
@@ -3096,10 +3096,29 @@
 @item @var{acdir}
 @end enumerate
 
address@hidden Modifying the macro search path: @env{ACLOCAL_PATH}
address@hidden @env{ACLOCAL_PATH}
+
+The environment variable @env{ACLOCAL_PATH} may be used to pass a
+colon-separated list of directories to @command{aclocal}, which will
+be searched before the default path for third-party modules.  Thus,
address@hidden/foo:/bar aclocal} results in the following search path:
+
address@hidden
address@hidden @address@hidden
address@hidden @file{/foo}
address@hidden @file{/bar}
address@hidden @var{acdir}
address@hidden enumerate
+
+Setting @env{ACLOCAL_PATH} allows to choose the right variant when
+several versions of third-party macro files are installed in different
+directories.
+
 @subsubsection Modifying the macro search path: @file{dirlist}
 @cindex @file{dirlist}
 
-There is a third mechanism for customizing the search path.  If a
+There is a fourth mechanism for customizing the search path.  If a
 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
 contain a list of directory patterns, one per line.  @command{aclocal}
 expands these patterns to directory names, and adds them to the search
Index: tests/Makefile.am
===================================================================
RCS file: /cvs/automake/automake/tests/Makefile.am,v
retrieving revision 1.622
diff -u -r1.622 Makefile.am
--- tests/Makefile.am   22 Jul 2007 08:48:18 -0000      1.622
+++ tests/Makefile.am   15 Aug 2007 05:33:27 -0000
@@ -25,6 +25,7 @@
 acloca20.test \
 acloca21.test \
 acloca22.test \
+acloca23.test \
 acoutnoq.test \
 acoutpt.test \
 acoutpt2.test \
--- /dev/null   2007-08-04 15:05:22.228065249 +0200
+++ tests/acloca23.test 2007-08-15 07:32:53.000000000 +0200
@@ -0,0 +1,67 @@
+#! /bin/sh
+# Copyright (C) 2003, 2005, 2007  Free Software Foundation, Inc.
+#
+# This file is part of GNU Automake.
+#
+# GNU Automake is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# GNU Automake is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Automake; see the file COPYING.  If not, write to
+# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+# Boston, MA 02110-1301, USA.
+
+# Make sure ACLOCAL_PATH works as advertised.
+# This is modeled after acloca10.test.
+
+. ./defs || exit 1
+
+set -e
+
+cat >> configure.in << 'END'
+MACRO2
+MACRO1
+MACRO3
+END
+
+mkdir m4_1 m4_2 m4_3
+
+cat >m4_1/somedefs.m4 <<EOF
+AC_DEFUN([MACRO1], [echo macro11 >> foo])
+AC_DEFUN([MACRO2], [echo macro21 > foo])
+EOF
+
+cat >m4_2/somedefs.m4 <<EOF
+AC_DEFUN([MACRO1], [echo macro12 >> foo])
+EOF
+
+cat >m4_3/macro.m4 <<EOF
+AC_DEFUN([MACRO3], [echo macro3 >> foo])
+EOF
+
+env ACLOCAL_PATH="m4_1:m4_2:`pwd`/m4_3" $ACLOCAL --verbose
+$AUTOCONF
+./configure
+grep macro11 foo
+grep macro21 foo
+grep macro3 foo
+grep MACRO3 aclocal.m4
+test ! -f m4_1/macro.m4
+test ! -f m4_2/macro.m4
+
+env ACLOCAL_PATH="m4_2:m4_1:`pwd`/m4_3" $ACLOCAL --verbose
+$AUTOCONF
+./configure
+grep macro12 foo
+grep macro21 foo
+grep macro3 foo
+grep MACRO3 aclocal.m4
+test ! -f m4_1/macro.m4
+test ! -f m4_2/macro.m4