A macro that you write might need to use values that have previously
been computed by other macros. For example, AC_DECL_YYTEXT
examines the output of flex or lex, so it depends on
AC_PROG_LEX having been called first to set the shell variable
LEX.
Rather than forcing the user of the macros to keep track of the
dependencies between them, you can use the AC_REQUIRE macro to do
it automatically. AC_REQUIRE can ensure that a macro is only
called if it is needed, and only called once.
If the M4 macro macro-name has not already been called, call it
(without any arguments). Make sure to quote macro-name with
square brackets. macro-name must have been defined using
AC_DEFUN or else contain a call to AC_PROVIDE to indicate
that it has been called.
AC_REQUIRE must be used inside a macro defined by AC_DEFUN; it
must not be called from the top level. Also, it does not make sense to
require a macro that takes parameters.
AC_REQUIRE is often misunderstood. It really implements
dependencies between macros in the sense that if one macro depends upon
another, the latter is expanded before the body of the
former. To be more precise, the required macro is expanded before
the outermost defined macro in the current expansion stack.
In particular, ‘AC_REQUIRE([FOO])’ is not replaced with the body of
FOO. For instance, this definition of macros:
AC_DEFUN([TRAVOLTA], [test "$body_temperature_in_Celsius" -gt 38 && dance_floor=occupied]) AC_DEFUN([NEWTON_JOHN], [test "x$hair_style" = xcurly && dance_floor=occupied])
AC_DEFUN([RESERVE_DANCE_FLOOR], [if test "x`date +%A`" = xSaturday; then AC_REQUIRE([TRAVOLTA]) AC_REQUIRE([NEWTON_JOHN]) fi])
with this configure.ac
AC_INIT([Dance Manager], [1.0], [bug-dance@example.org]) RESERVE_DANCE_FLOOR if test "x$dance_floor" = xoccupied; then AC_MSG_ERROR([cannot pick up here, let's move]) fi
does not leave you with a better chance to meet a kindred soul on
days other than Saturday, since the call to RESERVE_DANCE_FLOOR
expands to:
test "$body_temperature_in_Celsius" -gt 38 && dance_floor=occupied test "x$hair_style" = xcurly && dance_floor=occupied if test "x`date +%A`" = xSaturday; then fi
This behavior was chosen on purpose: (i) it prevents messages in required macros from interrupting the messages in the requiring macros; (ii) it avoids bad surprises when shell conditionals are used, as in:
if …; then AC_REQUIRE([SOME_CHECK]) fi … SOME_CHECK
However, this implementation can lead to another class of problems. Consider the case where an outer macro first expands, then indirectly requires, an inner macro:
AC_DEFUN([TESTA], [[echo in A if test -n "$SEEN_A" ; then echo duplicate ; fi SEEN_A=:]]) AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B if test -z "$SEEN_A" ; then echo bug ; fi]]) AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) AC_DEFUN([OUTER], [[echo in OUTER] TESTA TESTC]) OUTER
Prior to Autoconf 2.64, the implementation of AC_REQUIRE
recognized that TESTB needed to be hoisted prior to the expansion
of OUTER, but because TESTA had already been directly
expanded, it failed to hoist TESTA. Therefore, the expansion of
TESTB occurs prior to its prerequisites, leading to the following
output:
in B bug in OUTER in A in C
Newer Autoconf is smart enough to recognize this situation, and hoists
TESTA even though it has already been expanded, but issues a
syntax warning in the process. This is because the hoisted expansion of
TESTA defeats the purpose of using AC_REQUIRE to avoid
redundant code, and causes its own set of problems if the hoisted macro
is not idempotent:
in A in B in OUTER in A duplicate in C
The bug is not in Autoconf, but in the macro definitions. If you ever
pass a particular macro name to AC_REQUIRE, then you are implying
that the macro only needs to be expanded once. But to enforce this,
either the macro must be declared with AC_DEFUN_ONCE (although
this only helps in Autoconf 2.64 or newer), or all
uses of that macro should be through AC_REQUIRE; directly
expanding the macro defeats the point of using AC_REQUIRE to
eliminate redundant expansion. In the example, this rule of thumb was
violated because TESTB requires TESTA while OUTER
directly expands it. One way of fixing the bug is to factor
TESTA into two macros, the portion designed for direct and
repeated use (here, named TESTA), and the portion designed for
one-shot output and used only inside AC_REQUIRE (here, named
TESTA_PREREQ). Then, by fixing all clients to use the correct
calling convention according to their needs:
AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]]) AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ if test -n "$SEEN_A" ; then echo duplicate ; fi SEEN_A=:]]) AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B if test -z "$SEEN_A" ; then echo bug ; fi]]) AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) AC_DEFUN([OUTER], [[echo in OUTER] TESTA TESTC]) OUTER
the resulting output will then obey all dependency rules and avoid any syntax warnings, whether the script is built with old or new Autoconf versions:
in A_PREREQ in B in OUTER in A in C
You can use the helper macros AS_IF and AS_CASE in
top-level code to enforce expansion of required macros outside of shell
conditional constructs; these helpers are not needed in the bodies of
macros defined by AC_DEFUN.
You are furthermore encouraged, although not required, to
put all AC_REQUIRE calls
at the beginning of a macro. You can use dnl to avoid the empty
lines they leave.
Autoconf will normally warn if an AC_REQUIRE call refers to a
macro that has not been defined. However, the aclocal tool
relies on parsing an incomplete set of input files to trace which macros
have been required, in order to then pull in additional files that
provide those macros; for this particular use case, pre-defining the
macro m4_require_silent_probe will avoid the warnings.