8.5.4.1 Prerequisite Macros

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.

Macro: AC_REQUIRE (macro-name)

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 date | grep '^Sat.*pm' >/dev/null 2>&1; 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 at other times than Saturday night since it expands into:

test "$body_temperature_in_Celsius" -gt "38" &&
  dance_floor=occupied
test "x$hair_style" = xcurly &&
  dance_floor=occupied
fi
if date | grep '^Sat.*pm' >/dev/null 2>&1; 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

The helper macros AS_IF and AS_CASE may be used to enforce expansion of required macros outside of shell conditional constructs. 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.