autoconf: Macro Definitions

1 
1 10.1 Macro Definitions
1 ======================
1 
1  -- Macro: AC_DEFUN (NAME, [BODY])
1      Autoconf macros are defined using the `AC_DEFUN' macro, which is
1      similar to the M4 builtin `m4_define' macro; this creates a macro
1      named NAME and with BODY as its expansion.  In addition to
1      defining a macro, `AC_DEFUN' adds to it some code that is used to
1      constrain the order in which macros are called, while avoiding
1      redundant output (⇒Prerequisite Macros).
1 
1    An Autoconf macro definition looks like this:
1 
1      AC_DEFUN(MACRO-NAME, MACRO-BODY)
1 
1    You can refer to any arguments passed to the macro as `$1', `$2',
1 etc.  ⇒How to define new macros (m4.info)Definitions, for more
1 complete information on writing M4 macros.
1 
1    Most macros fall in one of two general categories.  The first
1 category includes macros which take arguments, in order to generate
1 output parameterized by those arguments.  Macros in this category are
1 designed to be directly expanded, often multiple times, and should not
1 be used as the argument to `AC_REQUIRE'.  The other category includes
1 macros which are shorthand for a fixed block of text, and therefore do
1 not take arguments.  For this category of macros, directly expanding
1 the macro multiple times results in redundant output, so it is more
1 common to use the macro as the argument to `AC_REQUIRE', or to declare
1 the macro with `AC_DEFUN_ONCE' (⇒One-Shot Macros).
1 
1    Be sure to properly quote both the MACRO-BODY _and_ the MACRO-NAME
1 to avoid any problems if the macro happens to have been previously
1 defined.
1 
1    Each macro should have a header comment that gives its prototype,
1 and a brief description.  When arguments have default values, display
1 them in the prototype.  For example:
1 
1      # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
1      # --------------------------------------
1      m4_define([AC_MSG_ERROR],
1        [{ AS_MESSAGE([error: $1], [2])
1           exit m4_default([$2], [1]); }])
1 
1    Comments about the macro should be left in the header comment.  Most
1 other comments make their way into `configure', so just keep using `#'
1 to introduce comments.
1 
1    If you have some special comments about pure M4 code, comments that
1 make no sense in `configure' and in the header comment, then use the
1 builtin `dnl': it causes M4 to discard the text through the next
1 newline.
1 
1    Keep in mind that `dnl' is rarely needed to introduce comments;
1 `dnl' is more useful to get rid of the newlines following macros that
1 produce no output, such as `AC_REQUIRE'.
1 
1    Public third-party macros need to use `AC_DEFUN', and not
11 `m4_define', in order to be found by `aclocal' (⇒Extending
 aclocal (automake)Extending aclocal.).  Additionally, if it is ever
1 determined that a macro should be made obsolete, it is easy to convert
1 from `AC_DEFUN' to `AU_DEFUN' in order to have `autoupdate' assist the
1 user in choosing a better alternative, but there is no corresponding
1 way to make `m4_define' issue an upgrade notice (⇒AU_DEFUN).
1 
1    There is another subtle, but important, difference between using
1 `m4_define' and `AC_DEFUN': only the former is unaffected by
1 `AC_REQUIRE'.  When writing a file, it is always safe to replace a
1 block of text with a `m4_define' macro that will expand to the same
1 text.  But replacing a block of text with an `AC_DEFUN' macro with the
1 same content does not necessarily give the same results, because it
1 changes the location where any embedded but unsatisfied `AC_REQUIRE'
1 invocations within the block will be expanded.  For an example of this,
1 see ⇒Expanded Before Required.
1