[automake-commit] branch master updated: aclocal: add --aclocal-path option to override ACLOCAL_PATH envvar.

[Karl Berry]

This is an automated email from the git hooks/post-receive script.

karl pushed a commit to branch master
in repository automake.

View the commit online:
https://git.savannah.gnu.org/gitweb/?p=automake.git;a=commitdiff;h=eb20585d0221a7739b2ab957c5ba4fbac62888e1

The following commit(s) were added to refs/heads/master by this push:
     new eb20585d0 aclocal: add --aclocal-path option to override ACLOCAL_PATH 
envvar.
eb20585d0 is described below

commit eb20585d0221a7739b2ab957c5ba4fbac62888e1
Author: Mike Frysinger <vapier@gentoo.org>
AuthorDate: Tue Jun 18 10:32:09 2024 -0700

    aclocal: add --aclocal-path option to override ACLOCAL_PATH envvar.
    
    From 
https://lists.gnu.org/archive/html/automake-patches/2022-01/msg00029.html
    (plus wording tweaks from Karl; and thanks to Bogdan for research).
    
    * bin/aclocal.in (usage): relabel output of m4 search path
    components to be somewhat more correct (Karl), although it's still
    a mess.
    (parse_arguments): add new option --aclocal-path=s.
    (parse_ACLOCAL_PATH): use $aclocal_path instead of hardwiring envvar.
    * doc/automake.texi (aclocal Options): document it.
    (dirlist): new anchor so we can reference it.
    (Modifying the Macro Search Path: @file{ACLOCAL_PATH}): mention
    the option.
    (Possible future incompatibility): tone down; it might never happen.
    * t/aclocal-path-precedence.sh: test the option.
    * NEWS: mention the new option.
---
 NEWS                         |  3 ++
 bin/aclocal.in               | 43 +++++++++++++++++---------
 doc/automake.texi            | 72 ++++++++++++++++++++++++++++----------------
 t/aclocal-path-precedence.sh | 29 ++++++++++++++++++
 4 files changed, 107 insertions(+), 40 deletions(-)

diff --git a/NEWS b/NEWS
index b0268d268..bf8c72d32 100644
--- a/NEWS
+++ b/NEWS
@@ -41,6 +41,9 @@ New in 1.17:
     it should be the basename of the Texinfo file, extended with .info.
     (bug#54063)
 
+  - aclocal has a new option --aclocal-path to override $ACLOCAL_PATH.
+    (https://lists.gnu.org/archive/html/automake-patches/2022-01/msg00029.html)
+
   - The missing script also supports autoreconf, autogen, and perl.
     (https://lists.gnu.org/archive/html/automake-patches/2015-08/msg00000.html)
 
diff --git a/bin/aclocal.in b/bin/aclocal.in
index 140c5ad29..4d01f3a4d 100644
--- a/bin/aclocal.in
+++ b/bin/aclocal.in
@@ -62,11 +62,12 @@ $perl_threads = 0;
 # @user_includes can be augmented with -I or AC_CONFIG_MACRO_DIRS.
 # @automake_includes can be reset with the '--automake-acdir' option.
 # @system_includes can be augmented with the 'dirlist' file or the
-# ACLOCAL_PATH environment variable, and reset with the '--system-acdir'
-# option.
+# --aclocal-path option/ACLOCAL_PATH environment variable, and reset
+# with the '--system-acdir' 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 +1032,8 @@ Generate 'aclocal.m4' by scanning 'configure.ac' or 
'configure.in'
 
 Options:
       --automake-acdir=DIR  directory holding automake-provided m4 files
+      --aclocal-path=PATH   colon-separated list of directories 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)
@@ -1055,18 +1058,27 @@ EOF
   # pages during Automake compilation, the environment is set to local values.
   # So don't include it in the installed man page.
   if (!$ENV{AUTOMAKE_HELP2MAN}) {
-    my $aclocal_automake_dir = $ENV{"ACLOCAL_AUTOMAKE_DIR"} || "";
-    my $aclocal_path = $ENV{"ACLOCAL_PATH"} || "";
+    my $aclocal_automake_dir_env = $ENV{"ACLOCAL_AUTOMAKE_DIR"} || "";
+    my $aclocal_path_env = $ENV{"ACLOCAL_PATH"} || "";
     print <<"EOF";
 
-Current m4 search paths (in order):
-  -I dirs:                  @user_includes
-  --automake-acdir:         @automake_includes
-  \$ACLOCAL_AUTOMAKE_DIR:    $aclocal_automake_dir
-  \$ACLOCAL_PATH:            $aclocal_path
-  --system-acdir:           @system_includes
+m4 search paths (in order):
+      user includes: @user_includes
+  automake includes: @automake_includes
+    system includes: @system_includes
+       aclocal path: $aclocal_path
+
+Environment variable settings, for reference:
+  \$ACLOCAL_AUTOMAKE_DIR:    $aclocal_automake_dir_env
+  \$ACLOCAL_PATH:            $aclocal_path_env
 EOF
   }
+  # The above listing of paths is rather a mess.  Because we don't
+  # compute all paths before outputting the help, the aclocal paths and
+  # ac_config_macro_dirs are not added to the system includes.  And
+  # because we don't keep track separately of command line values given
+  # to -I and the other options, we can't report them separately from
+  # the environment variables.
 
   print <<'EOF';
 
@@ -1106,6 +1118,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,
@@ -1160,11 +1173,11 @@ sub parse_arguments ()
     }
 }
 
-# Add any directory listed in the 'ACLOCAL_PATH' environment variable
-# to the list of system include directories.
+# Add any directory listed in $aclocal_path to the list of system
+# include directories.
 sub parse_ACLOCAL_PATH ()
 {
-  return if not defined $ENV{"ACLOCAL_PATH"};
+  return if not $aclocal_path;
   
   # Directories in ACLOCAL_PATH should take precedence over system
   # directories, so we use unshift.  However, directories that
@@ -1176,7 +1189,7 @@ sub parse_ACLOCAL_PATH ()
   # but this seems simpler.
   my $path_sep = $^O =~ /^(os2|mswin)/i ? ';' : ':';
   
-  foreach my $dir (reverse split $path_sep, $ENV{"ACLOCAL_PATH"})
+  foreach my $dir (reverse split $path_sep, $aclocal_path)
     {
       unshift (@system_includes, $dir) if $dir ne '' && -d $dir;
     }
@@ -1193,6 +1206,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 0ae2d4f33..4bfff91c3 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3372,6 +3372,19 @@ 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{path}
+@opindex --aclocal-path
+Look for local third-party macro files (and the special @file{dirlist}
+file, @pxref{dirlist}) along @var{path} (a colon-separated list of
+directories) instead of in the installation directory.  (This can be
+used for building against alternative system roots (``sysroots'') for
+finding headers and libraries.)
+
+@vindex ACLOCAL_PATH
+The environment variable @env{ACLOCAL_PATH} provides another way to
+set the search path containing local third-party macro files. This
+variable is ignored if the @option{--aclocal-path} option is specified.
+
 @item --system-acdir=@var{dir}
 @opindex --system-acdir
 Look for the system-wide third-party macro files (and the special
@@ -3529,6 +3542,7 @@ Any extra directories specified using @option{-I} options
 @item @var{acdir}
 @end enumerate
 
+@anchor{dirlist}
 @subsubheading Modifying the Macro Search Path: @file{dirlist}
 @cindex @file{dirlist}
 
@@ -3614,40 +3628,46 @@ 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}/@file{ACLOCAL_PATH}
+@opindex @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
+also the simplest.  Any directory included in the colon-separated path
+given to the @option{--aclocal-path} command-line option or in the
+@env{ACLOCAL_PATH} environment variable is added to the search 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}.
-
-@c Keep in sync with aclocal-path-installed.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.
-@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
+These directories take 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 @option{--aclocal-path}/@env{ACLOCAL_PATH}.
+
+@c Keep in sync with aclocal-path-install.sh
+If the @option{--install} option is used, any @file{.m4} file
+containing a required macro that is found in a directory listed in
+@option{--aclocal-path}/@env{ACLOCAL_PATH} will be installed locally.
+@c Keep in sync with aclocal-path-install-serial.sh
+In this case, serial numbers in @file{.m4} are honored too
+(@pxref{Serials}).
+
+Conversely to @file{dirlist},
+@option{--aclocal-path}/@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.
 
-@subsubheading Planned future incompatibility
+@subsubheading Possible future incompatibility
 
-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}}
+The order in which the directories in the macro search path are
+currently looked up is confusing and/or suboptimal in various aspects.
+In particular, directories in
+@option{--aclocal-path}/@env{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!}
+directories in @file{@var{acdir}/dirlist} might end up taking
+precedence over @file{@var{acdir}}.  Although there are no plans to
+change the current behavior, if it causes problems, the default might
+need to be changed, and the current behavior retained as an
+option.
 
 @node Extending aclocal
 @subsection Writing your own aclocal macros
diff --git a/t/aclocal-path-precedence.sh b/t/aclocal-path-precedence.sh
index 57b1adadf..5dbf20f04 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
+
 :