From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 11 Oct 2004 20:25:41 +0000 (+0000)
Subject: (One-Shot Macros): New node.
X-Git-Tag: AUTOCONF-2.59c~618
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1d037b8bc336b8135b7d43fa95067d367c30ebf0;p=thirdparty%2Fautoconf.git

(One-Shot Macros): New node.
---

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index b0c8410b8..c38974d67 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -452,6 +452,7 @@ Dependencies Between Macros
 
 * Prerequisite Macros::         Ensuring required information
 * Suggested Ordering::          Warning about possible ordering problems
+* One-Shot Macros::             Ensuring a macro is called only once
 
 Portable Shell Programming
 
@@ -462,6 +463,7 @@ Portable Shell Programming
 * Shell Substitutions::         Variable and command expansions
 * Assignments::                 Varying side effects of assignments
 * Parentheses::                 Parentheses in shell scripts
+* Slashes::                     Slashes in shell scripts
 * Special Shell Variables::     Variables you should not change
 * Limitations of Builtins::     Portable use of not so portable /bin/sh
 * Limitations of Usual Tools::  Portable use of portable tools
@@ -8947,6 +8949,7 @@ called in an order that might cause incorrect operation.
 @menu
 * Prerequisite Macros::         Ensuring required information
 * Suggested Ordering::          Warning about possible ordering problems
+* One-Shot Macros::             Ensuring a macro is called only once
 @end menu
 
 @node Prerequisite Macros
@@ -9089,6 +9092,31 @@ macro @var{called-macro-name} must have been defined using
 that it has been called.
 @end defmac
 
+@node One-Shot Macros
+@subsection One-Shot Macros
+@cindex One-shot macros
+@cindex Macros, called once
+
+Some macros should be called only once, either because calling them
+multiple time is unsafe, or because it is bad style.  For instance
+Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
+(@pxref{Canonicalizing}) are evaluated only once, because it makes no
+sense to run these expensive checks more than once.  Such one-shot
+macros can be defined using @code{AC_DEFUN_ONCE}.
+
+@defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
+@acindex{DEFUN_ONCE}
+
+Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
+Definitions}), and emit a warning any time the macro is called more than
+once.
+@end defmac
+
+Obviously it is not sensible to evaluate a macro defined by
+@code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}, most of the
+times you will want to use @code{AC_REQUIRE} (@pxref{Prerequisite
+Macros}).
+
 @node Obsoleting Macros
 @section Obsoleting Macros
 @cindex Obsoleting macros