(Hello. This is my first time making a patch to Autoconf.)
The descriptions and examples of AC_REQUIRE didn't give an idea of how
to properly use it. It was loaded with bad examples at the start, and
not good example of use. Also it didn't explain _why_ we should use
AS_IF and AS_CASE around macros that may AC_REQUIRE something else.
So I took the effort to write a good example for it.
Also I removed the sentence "it does not make sense to require a macro
that takes parameters" as I wrote the example, because (1) the example
is the potential use case that a macro with arguments may be required,
and (2) the Autoconf upstream developers are not the judge on how
downstream use it.
---
doc/autoconf.texi | 112 +++++++++++++++++++++++++++++-----------------
1 file changed, 70 insertions(+), 42 deletions(-)
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 12734446..65da9063 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -14786,24 +14786,77 @@ called if it is needed, and only called once.
@defmac AC_REQUIRE (@var{macro-name})
@acindex{REQUIRE}
+@code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}.
If the M4 macro @var{macro-name} has not already been called, call it
-(without any arguments). Make sure to quote @var{macro-name} with
-square brackets. @var{macro-name} must have been defined using
-@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
+(without any arguments) @emph{before} the expansion of the macro calling
+@code{AC_REQUIRE}. To be more precise, the required macro is expanded before
+the outermost defined macro in the current expansion stack.
+
+The @var{macro-name} argument must be quoted with square brackets.
+The macro @var{macro-name} must have been defined using @code{AC_DEFUN} or
+else contain a call to @code{AC_PROVIDE} to indicate
that it has been called.
-@code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
-must not be called from the top level. Also, it does not make sense to
-require a macro that takes parameters.
+@code{AC_REQUIRE} must not be called from the top level.
@end defmac
-@code{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 @emph{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, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
-@code{FOO}. For instance, this definition of macros:
+The body of the macro that would be called by @code{AC_REQUIRE} should contain
+shell code that works on the top level. For example it may contain shell
+function definitions in global scope, or checking code that needs to performed
+@emph{unconditionally} prior to the macro requiring it.
+
+Here is a proper example of using @code{AC_REQUIRE}:
+
+@example
+@group
+AC_DEFUN([CHECK_PROG1],
+[AC_CHECK_PROGS([PROG1], [prog1])
+])
+@end group
+
+@group
+AC_DEFUN([CHECK_FEATURE1],
+[AC_REQUIRE([CHECK_PROG1])dnl
+AC_MSG_CHECKING([for feature1])
+AS_IF([$PROG1 some-arguments],
+ [AC_MSG_RESULT([yes])],
+ [AC_MSG_RESULT([no])
+ AC_MSG_ERROR([prog1 is needed for feature1])])
+])
+@end group
+
+@group
+AS_IF([test "x$enable_feature1" = xyes],
+ [CHECK_FEATURE1])
+@end group
+@end example
+
+Note that in the example above, @code{PROG1} will be checked regardless of the
+value of @code{$enable_feature1}. This is by design, since the @code{PROG1}
+check might be required by other macros, each might be called from within a
+conditional (such as @code{$enable_feature2}) in the future.
+
+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 the required macros are expanded within shell
+conditionals, rather than on the top level.
+
+When a macro that may call @code{AC_REQUIRE} is used inside a conditional, you
+should use the helper macros @code{AS_IF} and @code{AS_CASE} instead of the
+shell's @code{if} and @code{case},
+to enforce expansion of required macros outside of shell
+conditional constructs; these helpers are not needed in the bodies of
+macros defined by @code{AC_DEFUN}.
+
+You are furthermore encouraged, although not required, to
+put all @code{AC_REQUIRE} calls
+at the beginning of a macro. You can use @code{dnl} to avoid the empty
+lines they leave.
+
+One common misunderstanding of @code{AC_REQUIRE} is that
+@samp{AC_REQUIRE([FOO])} would expand to the body of @code{FOO}. No it doesn't.
+The @code{AC_REQUIRE} call itself expands to nothing.
+For instance, this definition of macros:
@example
@group
@@ -14822,17 +14875,14 @@ AC_DEFUN([RESERVE_DANCE_FLOOR],
AC_REQUIRE([NEWTON_JOHN])
fi])
@end group
-@end example
-
-@noindent
-with this @file{configure.ac}
-@example
+@group
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
+@end group
@end example
@noindent
@@ -14853,21 +14903,8 @@ fi
@end group
@end example
-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:
-
-@example
-@group
-if @dots{}; then
- AC_REQUIRE([SOME_CHECK])
-fi
-@dots{}
-SOME_CHECK
-@end group
-@end example
-
-However, this implementation can lead to another class of problems.
+If a macro name passed to a call of @code{AC_REQUIRE} is also called directly
+in the body of another macro, be careful of potential bugs.
Consider the case where an outer macro first expands, then indirectly
requires, an inner macro:
@@ -14960,15 +14997,6 @@ in A
in C
@end example
-You can use the helper macros @code{AS_IF} and @code{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 @code{AC_DEFUN}.
-You are furthermore encouraged, although not required, to
-put all @code{AC_REQUIRE} calls
-at the beginning of a macro. You can use @code{dnl} to avoid the empty
-lines they leave.
-
Autoconf will normally warn if an @code{AC_REQUIRE} call refers to a
macro that has not been defined. However, the @command{aclocal} tool
relies on parsing an incomplete set of input files to trace which macros
--
2.49.0
