[PATCH] AC_CONFIG_MACRO_DIRS: improve tracing and add sanity checks

[Eric Blake]

Too many legacy tools exist for us to unilaterally quit supporting
AC_CONFIG_MACRO_DIR - it is feasible for someone to want their
package to bootstrap with both automake 1.13 and libtool 2.4.2,
where the newer automake will only trace the new style of multiple
directory listings, but the older libtool does a sed and settles
on the one use of the old name.  So, we let both macros forward
to a new tracing macro, which also has the benefit of sanitizing
calls into one directory per trace; we also ensure that the old
macro is always traced, and appears at most once and before any
use of the new macro.

* doc/autoconf.texi (Input) <AC_CONFIG_MACRO_DIRS>: Document how
to trace this macro.
* lib/autom4te.in (Autoreconf-preselections)
(Automake-preselections): Preselect this trace.
* lib/autoconf/general.m4 (AC_CONFIG_MACRO_DIR_TRACE): New trace.
(_AC_CONFIG_MACRO_DIRS_USED, _AC_CONFIG_MACRO_DIRS): New internal
macros.
(AC_CONFIG_MACRO_DIRS, AC_CONFIG_MACRO_DIR): Use them.
* tests/tools.at (autoconf --trace: AC_CONFIG_MACRO_DIRS): New
test.
---
 doc/autoconf.texi       |  8 ++++--
 lib/autoconf/general.m4 | 37 +++++++++++++++++++++++---
 lib/autom4te.in         |  2 ++
 tests/tools.at          | 71 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 112 insertions(+), 6 deletions(-)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index ff8298a..d1483b8 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -2114,11 +2114,14 @@ Input
 @defmacx AC_CONFIG_MACRO_DIR (@var{dir})
 @acindex{CONFIG_MACRO_DIRS}
 @acindex{CONFIG_MACRO_DIR}
address@hidden
 Specify the given directories as the location of additional local Autoconf
 macros.  These macros are intended for use by commands like
 @command{autoreconf} or @command{aclocal} that trace macro calls; they should
 be called directly from @file{configure.ac} so that tools that install
-macros for @command{aclocal} can find the macros' declarations.
+macros for @command{aclocal} can find the macros' declarations.  Tools
+that want to learn which directories have been selected should trace
address@hidden, which will be called once per directory.

 AC_CONFIG_MACRO_DIRS is the preferred form, and can be called multiple
 times and with multiple arguments; in such cases, directories in earlier
@@ -2135,7 +2138,8 @@ Input
 AC_CONFIG_MACRO_DIRS([dir3 dir4])
 @end smallexample

-should cause the directories to be searched in this order:
+will cause the trace of AC_CONFIG_MACRO_DIR_TRACE to appear four times,
+and should cause the directories to be searched in this order:
 @samp{dir1 dir2 dir3 dir4}.

 Note that if you use @command{aclocal} from an Automake release prior to
diff --git a/lib/autoconf/general.m4 b/lib/autoconf/general.m4
index 96deb1e..5bc7f83 100644
--- a/lib/autoconf/general.m4
+++ b/lib/autoconf/general.m4
@@ -1727,18 +1727,47 @@ AC_PROVIDE([AC_CONFIG_AUX_DIR_DEFAULT])dnl
 ## ------------------------ ##


+# AC_CONFIG_MACRO_DIR_TRACE(DIR)
+# ------------------------------
+# This macro exists solely for tracing - never invoke it directly.
+# It will be called once per directory listed in either form of
+# AC_CONFIG_MACRO_DIR[S].
+m4_define([AC_CONFIG_MACRO_DIR_TRACE],
+[m4_fatal([Do not invoke $0 directly])])
+
+# _AC_CONFIG_MACRO_DIRS_USED
+# --------------------------
+# Internal witness macro, redefined to empty after first directory is traced.
+m4_define([_AC_CONFIG_MACRO_DIRS_USED], [-])
+
+# _AC_CONFIG_MACRO_DIRS(CALLER, DIR)
+# ----------------------------------
+# Internal workhorse macro to ensure a sane calling pattern of CALLER, and
+# eventually trace DIR through the documented public trace point.
+m4_define([_AC_CONFIG_MACRO_DIRS],
+[m4_if([$1], [-AC_CONFIG_MACRO_DIRS], [AC_CONFIG_MACRO_DIR([$2])],
+       [$1], [AC_CONFIG_MACRO_DIR], [m4_fatal([$1 can only be used once])],
+  [m4_define([$0_USED])m4_pushdef([AC_CONFIG_MACRO_DIR_TRACE])]]dnl
+[[AC_CONFIG_MACRO_DIR_TRACE([$2])m4_popdef([AC_CONFIG_MACRO_DIR_TRACE])])])
+
 # AC_CONFIG_MACRO_DIRS(DIR-1 [DIR-2 ... DIR-n])
 # --------------------------------------------
 # Declare directories containing additional macros for aclocal.
 # This macro can be called multiple times, and with multiple arguments.
-AC_DEFUN([AC_CONFIG_MACRO_DIRS], [])
+# Do not trace this macro; instead trace AC_CONFIG_MACRO_DIR_TRACE.
+# If no directory has been traced yet, then this macro also triggers
+# a trace of AC_CONFIG_MACRO_DIR on the first directory.
+AC_DEFUN([AC_CONFIG_MACRO_DIRS],
+[m4_map_args_w([$1], [_$0(_$0_USED()[$0], ], [)])])

 # AC_CONFIG_MACRO_DIR(DIR)
 # ------------------------
 # Declare directory containing additional macros for aclocal.
-# This is obsoleted by AC_CONFIG_MACRO_DIRS, and kept only for
-# backward compatibility.
-AC_DEFUN([AC_CONFIG_MACRO_DIR], [])
+# This macro exists for backward compatibility; while tools can trace this,
+# we recommend tracing AC_CONFIG_MACRO_DIR_TRACE instead.  This macro can
+# only be used once, and must not be used after AC_CONFIG_MACRO_DIRS.
+AC_DEFUN([AC_CONFIG_MACRO_DIR],
+[_$0S(_$0S_USED()[$0], [$1])])


 ## --------------------- ##
diff --git a/lib/autom4te.in b/lib/autom4te.in
index 1eb1709..cd621a2 100644
--- a/lib/autom4te.in
+++ b/lib/autom4te.in
@@ -42,6 +42,7 @@ args: --preselect AC_CONFIG_FILES
 args: --preselect AC_CONFIG_HEADERS
 args: --preselect AC_CONFIG_LIBOBJ_DIR
 args: --preselect AC_CONFIG_LINKS
+args: --preselect AC_CONFIG_MACRO_DIR_TRACE
 args: --preselect AC_FC_FREEFORM
 args: --preselect AC_FC_SRCEXT
 args: --preselect AC_FC_PP_DEFINE
@@ -93,6 +94,7 @@ end-language: "Automake-preselections"
 begin-language: "Autoreconf-preselections"
 args: --preselect AC_CONFIG_AUX_DIR
 args: --preselect AC_CONFIG_HEADERS
+args: --preselect AC_CONFIG_MACRO_DIR_TRACE
 args: --preselect AC_CONFIG_SUBDIRS
 args: --preselect AC_INIT
 args: --preselect AC_PROG_LIBTOOL
diff --git a/tests/tools.at b/tests/tools.at
index 4ffe3da..675cdfd 100644
--- a/tests/tools.at
+++ b/tests/tools.at
@@ -358,6 +358,77 @@ AT_CHECK_AUTOCONF([[-t define:'$1' -i| sed -n '$p']],
 AT_CLEANUP


+# autoconf --trace: AC_CONFIG_MACRO_DIRS
+# --------------------------------------
+AT_SETUP([autoconf --trace: AC_CONFIG_MACRO_DIRS])
+AT_KEYWORDS([AC_CONFIG_MACRO_DIR AC_CONFIG_MACRO_DIR_TRACE])
+
+AT_DATA([configure.ac],
+[[AC_INIT
+AC_CONFIG_MACRO_DIR([dir1])
+AC_CONFIG_MACRO_DIRS([dir2 dir3 \
+dir4])
+AC_CONFIG_MACRO_DIRS([dir5])
+]])
+
+# Legacy tracing
+AT_CHECK_AUTOCONF([-t AC_CONFIG_MACRO_DIR], 0,
+[[configure.ac:2:AC_CONFIG_MACRO_DIR:dir1
+]])
+
+# Preferred tracing
+AT_CHECK_AUTOCONF([-t AC_CONFIG_MACRO_DIR_TRACE], 0,
+[[configure.ac:2:AC_CONFIG_MACRO_DIR_TRACE:dir1
+configure.ac:3:AC_CONFIG_MACRO_DIR_TRACE:dir2
+configure.ac:3:AC_CONFIG_MACRO_DIR_TRACE:dir3
+configure.ac:3:AC_CONFIG_MACRO_DIR_TRACE:dir4
+configure.ac:5:AC_CONFIG_MACRO_DIR_TRACE:dir5
+]])
+
+# Legacy macro can only be used once
+AT_DATA([configure.ac],
+[[AC_INIT
+AC_CONFIG_MACRO_DIR([dir1])
+AC_CONFIG_MACRO_DIR([dir2])
+]])
+AT_CHECK_AUTOCONF([], [1], [], [stderr])
+AT_CHECK([grep 'error: AC_CONFIG_MACRO_DIR can only be used once' stderr],
+[], [ignore])
+
+# Legacy macro must be used first, if present
+AT_DATA([configure.ac],
+[[AC_INIT
+AC_CONFIG_MACRO_DIRS([dir1])
+AC_CONFIG_MACRO_DIR([dir2])
+]])
+AT_CHECK_AUTOCONF([], [1], [], [stderr])
+AT_CHECK([grep 'error: AC_CONFIG_MACRO_DIR can only be used once' stderr],
+[], [ignore])
+
+# Only use the public macros
+AT_DATA([configure.ac],
+[[AC_INIT
+AC_CONFIG_MACRO_DIR_TRACE([dir1])
+]])
+AT_CHECK_AUTOCONF([], [1], [],
+[[configure.ac:2: error: Do not invoke AC_CONFIG_MACRO_DIR_TRACE directly
+configure.ac:2: the top level
+autom4te: m4 failed with exit status: 1
+]])
+
+# Legacy macro use is not required, but still gets traced
+AT_DATA([configure.ac],
+[[AC_INIT
+AC_CONFIG_MACRO_DIRS([dir1])
+AC_CONFIG_MACRO_DIRS([dir2])
+]])
+AT_CHECK_AUTOCONF([], [0], [], [])
+AT_CHECK_AUTOCONF([-t AC_CONFIG_MACRO_DIR], [0],
+[[configure.ac:2:AC_CONFIG_MACRO_DIR:dir1
+]])
+
+AT_CLEANUP
+

 ## ---------------------------- ##
 ## autoconf: forbidden tokens.  ##
-- 
1.7.11.7