[PATCH v2] aclocal: add --aclocal-path option to override $ACLOCAL_PATH

The $ACLOCAL_PATH env var is useful, but setting environment vars
is a bit clunky.  Add an --aclocal-path option to override it like
we already have with --automake-acdir.

* bin/aclocal.in: Add --aclocal-path to override ACLOCAL_PATH.
* doc/automake.texi: Document --aclocal-path.
* t/aclocal-path-precedence.sh: Add --aclocal-path coverage.
---
 NEWS                         |  8 ++++++++
 bin/aclocal.in               | 11 +++++++++--
 doc/automake.texi            | 30 +++++++++++++++++++++---------
 t/aclocal-path-precedence.sh | 29 +++++++++++++++++++++++++++++
 4 files changed, 67 insertions(+), 11 deletions(-)

diff --git a/NEWS b/NEWS
index 121fe820eeef..5507cdd6f78a 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,14 @@ please see NEWS-2.0 and start following the advice there now.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+New in 1.17:
+
+* New features added
+
+  - Aclocal has a --aclocal-path option to override $ACLOCAL_PATH.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 New in 1.16.5:
 
 * Bugs fixed
diff --git a/bin/aclocal.in b/bin/aclocal.in
index 77fbfd7e4acf..db80634fcd70 100644
--- a/bin/aclocal.in
+++ b/bin/aclocal.in
@@ -64,9 +64,11 @@ $perl_threads = 0;
 # @system_includes can be augmented with the 'dirlist' file or the
 # ACLOCAL_PATH environment variable, and reset with the '--system-acdir'
 # option.
+# @aclocal_path can be reset with the '--aclocal-path' option.
 my @user_includes = ();
 my @automake_includes = ('@datadir@/aclocal-' . $APIVERSION);
 my @system_includes = ('@datadir@/aclocal');
+my $aclocal_path = '';
 
 # Whether we should copy M4 file in $user_includes[0].
 my $install = 0;
@@ -1031,6 +1033,8 @@ Generate 'aclocal.m4' by scanning 'configure.ac' or 'configure.in'
 
 Options:
       --automake-acdir=DIR  directory holding automake-provided m4 files
+      --aclocal-path=PATHS  colon-separated paths to search for third-party
+                              local files
       --system-acdir=DIR    directory holding third-party system-wide files
       --diff[=COMMAND]      run COMMAND [diff -u] on M4 files that would be
                             changed (implies --install and --dry-run)
@@ -1061,6 +1065,7 @@ Current m4 search paths (in order):
   -I dirs:                  @user_includes
   --automake-acdir:         @automake_includes
   \$ACLOCAL_AUTOMAKE_DIR:    $ENV{"ACLOCAL_AUTOMAKE_DIR"}
+  --aclocal-path:           $aclocal_path
   \$ACLOCAL_PATH:            $ENV{"ACLOCAL_PATH"}
   --system-acdir:           @system_includes
 EOF
@@ -1104,6 +1109,7 @@ sub parse_arguments ()
      'version'		=> \&version,
      'system-acdir=s'	=> sub { shift; @system_includes = @_; },
      'automake-acdir=s'	=> sub { shift; @automake_includes = @_; },
+     'aclocal-path=s'   => sub { shift; $aclocal_path = $_[0]; },
      'diff:s'		=> \$diff_command,
      'dry-run'		=> \$dry_run,
      'force'		=> \$force_output,
@@ -1162,12 +1168,11 @@ sub parse_arguments ()
 # to the list of system include directories.
 sub parse_ACLOCAL_PATH ()
 {
-  return if not defined $ENV{"ACLOCAL_PATH"};
   # Directories in ACLOCAL_PATH should take precedence over system
   # directories, so we use unshift.  However, directories that
   # come first in ACLOCAL_PATH take precedence over directories
   # coming later, which is why the result of split is reversed.
-  foreach my $dir (reverse split /:/, $ENV{"ACLOCAL_PATH"})
+  foreach my $dir (reverse split /:/, $aclocal_path)
     {
       unshift (@system_includes, $dir) if $dir ne '' && -d $dir;
     }
@@ -1184,6 +1189,8 @@ if (exists $ENV{"AUTOMAKE_UNINSTALLED"})
 
 @automake_includes = ($ENV{"ACLOCAL_AUTOMAKE_DIR"})
   if (exists $ENV{"ACLOCAL_AUTOMAKE_DIR"});
+$aclocal_path = ($ENV{"ACLOCAL_PATH"})
+  if (exists $ENV{"ACLOCAL_PATH"});
 
 parse_WARNINGS;		    # Parse the WARNINGS environment variable.
 parse_arguments;
diff --git a/doc/automake.texi b/doc/automake.texi
index 9916a41d4b79..ab158c249529 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3337,6 +3337,17 @@ The environment variable @env{ACLOCAL_AUTOMAKE_DIR} provides another
 way to set the directory containing automake-provided macro files.
 However @option{--automake-acdir} takes precedence over it.
 
+@item --aclocal-path=@var{dir}
+@opindex --aclocal-path
+Look for local third-party macro files (and the special @file{dirlist}
+file) in @var{dir} instead of in the installation directory.  This is
+typically used for building against local sysroots.
+
+@vindex ACLOCAL_PATH
+The environment variable @env{ACLOCAL_PATH} provides another way to
+set the directory containing local third-party macro files.  However
+@option{--aclocal-path} takes precedence over it.
+
 @item --system-acdir=@var{dir}
 @opindex --system-acdir
 Look for the system-wide third-party macro files (and the special
@@ -3579,37 +3590,38 @@ copy of Automake in your account and want @command{aclocal} to look for
 macros installed at other places on the system.
 
 @anchor{ACLOCAL_PATH}
-@subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
+@subsubheading Modifying the Macro Search Path: @option{--aclocal-path}
 @cindex @env{ACLOCAL_PATH}
 
 The fourth and last mechanism to customize the macro search path is
 also the simplest.  Any directory included in the colon-separated
-environment variable @env{ACLOCAL_PATH} is added to the search path
+@option{--aclocal-path} (@pxref{aclocal Options}) is added to the search
+path (defaulting to environment variable @env{ACLOCAL_PATH})
 @c Keep in sync with aclocal-path-precedence.sh
 and takes precedence over system directories (including those found via
 @file{dirlist}), with the exception of the versioned directory
 @var{acdir-APIVERSION} (@pxref{Macro Search Path}).  However, directories
 passed via @option{-I} will take precedence over directories in
-@env{ACLOCAL_PATH}.
+@option{--aclocal-path}.
 
-@c Keep in sync with aclocal-path-installed.sh
+@c Keep in sync with aclocal-path-install.sh
 Also note that, if the @option{--install} option is used, any @file{.m4}
 file containing a required macro that is found in a directory listed in
-@env{ACLOCAL_PATH} will be installed locally.
+@option{--aclocal-path} will be installed locally.
 @c Keep in sync with aclocal-path-installed-serial.sh
 In this case, serial numbers in @file{.m4} are honored too,
 @pxref{Serials}.
 
-Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
-using a global copy of Automake and want @command{aclocal} to look for
-macros somewhere under your home directory.
+Conversely to @file{dirlist}, @option{--aclocal-path} is useful if you
+are using a global copy of Automake and want @command{aclocal} to look
+for macros somewhere under your home directory.
 
 @subsubheading Planned future incompatibilities
 
 The order in which the directories in the macro search path are currently
 looked up is confusing and/or suboptimal in various aspects, and is
 probably going to be changed in the future Automake release.  In
-particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
+particular, directories in @option{--aclocal-path} and @file{@var{acdir}}
 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
 directories in @file{@var{acdir}/dirlist} might end up taking precedence
 over @file{@var{acdir}}.  @emph{This is a possible future incompatibility!}
diff --git a/t/aclocal-path-precedence.sh b/t/aclocal-path-precedence.sh
index c074911a41f5..6494b13eb918 100644
--- a/t/aclocal-path-precedence.sh
+++ b/t/aclocal-path-precedence.sh
@@ -26,6 +26,7 @@ FOO_MACRO
 BAR_MACRO
 AC_PROG_LIBTOOL
 AM_GNU_GETTEXT
+AC_OUTPUT
 END
 
 mkdir mdir1 mdir2 mdir3 sysdir extradir
@@ -88,4 +89,32 @@ $FGREP 'am__api_version' configure
 # A final sanity check.
 $FGREP '::fail' configure && exit 1
 
+# Same checks, but now with the command line option.
+ACLOCAL_PATH=mdir2:mdir1 $ACLOCAL -I mdir3 --system-acdir sysdir --aclocal-path "mdir1:mdir2"
+$ACLOCAL -I mdir3 --system-acdir sysdir --aclocal-path "mdir1:mdir2"
+$AUTOCONF
+
+$FGREP '::' configure # For debugging.
+
+# Directories coming first in ACLOCAL_PATH should take precedence
+# over those coming later.
+$FGREP '::pass-foo::' configure
+
+# Directories from '-I' options should take precedence over directories
+# in ACLOCAL_PATH.
+$FGREP '::pass-bar::' configure
+
+# Directories in ACLOCAL_PATH should take precedence over system acdir
+# (typically '${prefix}/share/aclocal'), and any directory added through
+# the 'dirlist' special file.
+$FGREP '::pass-gettext::' configure
+$FGREP '::pass-libtool::' configure
+
+# Directories in ACLOCAL_PATH shouldn't take precedence over the internal
+# automake acdir (typically '${prefix}/share/aclocal-${APIVERSION}').
+$FGREP 'am__api_version' configure
+
+# A final sanity check.
+$FGREP '::fail' configure && exit 1
+
 :
-- 
2.34.1