[PATCH] 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.
---
 bin/aclocal.in    | 12 +++++++++---
 doc/automake.texi | 30 +++++++++++++++++++++---------
 2 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/bin/aclocal.in b/bin/aclocal.in
index 77fbfd7e4acf..6f7086c6fb4c 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,7 @@ Generate 'aclocal.m4' by scanning 'configure.ac' or 'configure.in'
 
 Options:
       --automake-acdir=DIR  directory holding automake-provided m4 files
+      --aclocal-path=DIR    directory holding 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 +1064,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 +1108,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 = @_; },
      'diff:s'		=> \$diff_command,
      'dry-run'		=> \$dry_run,
      'force'		=> \$force_output,
@@ -1162,14 +1167,13 @@ 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 (@aclocal_path)
     {
-      unshift (@system_includes, $dir) if $dir ne '' && -d $dir;
+      unshift (@system_includes, $_) if $_ ne '' && -d $_;
     }
 }
 
@@ -1184,6 +1188,8 @@ if (exists $ENV{"AUTOMAKE_UNINSTALLED"})
 
 @automake_includes = ($ENV{"ACLOCAL_AUTOMAKE_DIR"})
   if (exists $ENV{"ACLOCAL_AUTOMAKE_DIR"});
+@aclocal_path = (reverse split /:/, $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!}
-- 
2.34.1