aclocal: deprecate ACLOCAL_AMFLAGS, trace AC_CONFIG_MACRO_DIR instead

Maintaining ACLOCAL_AMFLAGS in the Makefile.am to pass extra flags
to aclocal is (and have always been) quite of an hack.  For example,
autoreconf is forced to grep Makefile.am to honour those flags.  But
this is a bad obsolescent behaviour; in fact, the autotools have moved
consistently in the past years from custom grepping of Makefile.am and
configure.ac to tracing of m4 macro calls, which is more consistent,
more reliable and more flexible.

And when autoreconf is not used, the developer is forced to add *by hand*
the flags specified by ACLOCAL_AMFLAGS to the aclocal calls not triggered
by make rebuild rules; here lie again more duplication and more chances
for errors.

Moreover, ACLOCAL_AMFLAGS has only two typical use cases:

  - to instruct aclocal to look for extra macro definition in a local
    directory (as with "ACLOCAL_AMFLAGS = -I m4"); and

  - to further instruct aclocal to copy in that local directory the
    required third-party .m4 files found in the system-wide directory
    (as with "ACLOCAL_AMFLAGS = -I m4 --install").

The first use case can be better covered if aclocal can instead trace and
honours call to the AC_CONFIG_MACRO_DIR autoconf macro; and the second
use case shouldn't be considered really legitimate, as it is quite (and
subtly) brittle (see automake bug#9037).

Thus we now make aclocal trace AC_CONFIG_MACRO_DIR macro, and act
accordingly.  For backward compatibility, we continue to support the
ACLOCAL_AMFLAGS special variable (although removing any mention of it
from the documentation).  Future Automake releases will likely start
to warn about the use of that variable, and eventually remove support
for it altogether.

From a suggestion by Eric Blake.

This is a much simplified (and IMHO saner) version of the patch series
discussed in the threads:
<http://lists.gnu.org/archive/html/automake-patches/2010-10/msg00045.html>
<http://lists.gnu.org/archive/html/automake-patches/2010-12/msg00156.html>

* aclocal.in ($ac_config_macro_dir): New global variable.
(trace_used_macros): Also trace the macro 'AC_CONFIG_MACRO_DIR',
and set the '$ac_config_macro_dir' variable accordingly.
(parse_arguments): Code for diagnosis of '--install' used without
any user-specified include directory moved  ...
(while (1)): .. into the main loop.  Which now also updates the
list of user-specified include directories to include the directory
given as argument to the call (if any) of 'AC_CONFIG_MACRO_DIR'.
* lib/am/configure.am: Update comments.
* NEWS: Updated.
* doc/automake.texi: Likewise.  Also, stop advising the use of the
'--install' in ACLOCAL_AMFLAGS (see automake bug#9037 for a rationale),
and remove any reference to ACLOCAL_AMFLAGS (which is now considered
obsolescent).
* t/aclocal-path-install.sh: Adjust grepping check in the aclocal
error messages.
* t/subpkg.sh: Updated: add 'AC_CONFIG_MACRO_DIR' call to configure.ac,
remove setting of 'ACLOCAL_AMFLAGS' in Makefile.am and use of aclocal
command line arguments.
* t/subpkg2.sh: Likewise.
* t/subdir8.sh: Likewise.
* t/remake10c.sh: Likewise.
* t/remake8a.sh: Likewise.
* t/remake8b.sh: Likewise.
* t/aclocal4.sh: Likewise.
* t/aclocal6.sh: Likewise.
* t/acloca14.sh: Likewise.
* t/acloca22.sh: Likewise.
* t/aclocal5.sh: Likewise, and do not not invade the Automake
namespace (this avoids spurious failures).
* t/acloca14b.sh: New test, identical to the previous version of
'acloca14.test'; it is kept to verify backwards compatibility with
the use of ACLOCAL_AMFLAGS.
* t/acloca22b.sh: Likewise (but for 'acloca22.test').
* t/aclocal-amflags.sh: New test, check for backwards
compatibility that ACLOCAL_AMFLAGS still works.
* t/remake-macrodir.sh: New test, checking that aclocal's honoring of
AC_CONFIG_MACRO_DIR interacts nicely with automatic rebuild rules.
* t/list-of-tests.mk: Add the new tests.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

1 files changed, 46 insertions, 17 deletions

diff --git a/aclocal.in b/aclocal.in
index c7cde7d6d..e2e953626 100644
--- a/aclocal.in
+++ b/aclocal.in
@@ -52,7 +52,7 @@ $perl_threads = 0;
 # user-supplied directories first, then the directory containing the
 # automake macros, and finally the system-wide directories for
 # third-party macros.
-# @user_includes can be augmented with -I.
+# @user_includes can be augmented with -I or AC_CONFIG_MACRO_DIR.
 # @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'
@@ -143,10 +143,14 @@ my $m4_include_rx = "(m4_|m4_s|s)include\\((?:\\[([^]]+)\\]|([^],)\n]+))\\)";
 my $serial_line_rx = '^#\s*serial\s+(\S*)';
 my $serial_number_rx = '^\d+(?:\.\d+)*$';
 
-# Autoconf version
-# Set by trace_used_macros.
+# Autoconf version.  This variable is set by 'trace_used_macros'.
 my $ac_version;
 
+# Primary user directory containing extra m4 files for macros
+# definition, as extracted from call to macro AC_CONFIG_MACRO_DIR.
+# This variable is set by 'trace_used_macros'.
+my $ac_config_macro_dir;
+
 # If set, names a temporary file that must be erased on abnormal exit.
 my $erase_me;
 
@@ -719,13 +723,15 @@ sub trace_used_macros ()
   $traces .= join (' ',
 		   (map { "'$_'" }
 		    (grep { exists $files{$_} } @file_order))) . " ";
+
   # All candidate macros.
   $traces .= join (' ',
 		   (map { "--trace='$_:\$f::\$n::\$1'" }
 		    ('AC_DEFUN',
 		     'AC_DEFUN_ONCE',
 		     'AU_DEFUN',
-		     '_AM_AUTOCONF_VERSION')),
+		     '_AM_AUTOCONF_VERSION',
+		     'AC_CONFIG_MACRO_DIR')),
 		   # Do not trace $1 for all other macros as we do
 		   # not need it and it might contains harmful
 		   # characters (like newlines).
@@ -735,6 +741,8 @@ sub trace_used_macros ()
 
   my $tracefh = new Automake::XFile ("$traces $configure_ac |");
 
+  $ac_config_macro_dir = undef;
+
   my %traced = ();
 
   while ($_ = $tracefh->getline)
@@ -744,12 +752,19 @@ sub trace_used_macros ()
 
       $traced{$macro} = 1 if exists $macro_seen{$macro};
 
-      $map_traced_defs{$arg1} = $file
-	if ($macro eq 'AC_DEFUN'
-	    || $macro eq 'AC_DEFUN_ONCE'
-	    || $macro eq 'AU_DEFUN');
-
-      $ac_version = $arg1 if $macro eq '_AM_AUTOCONF_VERSION';
+      if ($macro eq 'AC_DEFUN' || $macro eq 'AC_DEFUN_ONCE'
+            || $macro eq 'AU_DEFUN')
+        {
+          $map_traced_defs{$arg1} = $file;
+        }
+      elsif ($macro eq '_AM_AUTOCONF_VERSION')
+        {
+          $ac_version = $arg1;
+        }
+      elsif ($macro eq 'AC_CONFIG_MACRO_DIR')
+        {
+          $ac_config_macro_dir = $arg1;
+        }
     }
 
   $tracefh->close;
@@ -1018,12 +1033,6 @@ sub parse_arguments ()
       $dry_run = 1;
     }
 
-  if ($install && !@user_includes)
-    {
-      fatal ("--install should copy macros in the directory indicated by the"
-	     . "\nfirst -I option, but no -I was supplied");
-    }
-
   # Finally, adds any directory listed in the 'dirlist' file.
   if (open (DIRLIST, "$system_includes[0]/dirlist"))
     {
@@ -1073,16 +1082,36 @@ $configure_ac = require_configure_ac;
 # we did not rerun aclocal, the next run of aclocal would produce a
 # different aclocal.m4.
 my $loop = 0;
+my $rerun_due_to_macrodir = 0;
 while (1)
   {
     ++$loop;
-    prog_error "too many loops" if $loop > 2;
+    prog_error "too many loops" if $loop > 2 + $rerun_due_to_macrodir;
 
     reset_maps;
     scan_m4_files;
     scan_configure;
     last if $exit_code;
     my %macro_traced = trace_used_macros;
+
+    if (!$rerun_due_to_macrodir && defined $ac_config_macro_dir)
+      {
+         # The directory specified by the AC_CONFIG_MACRO_DIR m4 macro
+         # (if any) must after the user includes specified explicitly
+         # with the '-I' option.
+         push @user_includes, $ac_config_macro_dir
+           if defined $ac_config_macro_dir;
+        # We might have to scan some new directory of .m4 files.
+        $rerun_due_to_macrodir++;
+        next;
+      }
+
+    if ($install && !@user_includes)
+      {
+        fatal "installation of third-party macros impossible without " .
+              "-I options nor AC_CONFIG_MACRO_DIR m4 macro";
+      }
+
     last if write_aclocal ($output_file, keys %macro_traced);
     last if $dry_run;
   }