File: autoconf.info,  Node: Macro Definitions,  Next: Macro Names,  Up: Writing Autoconf Macros

10.1 Macro Definitions
======================

 -- Macro: AC_DEFUN (NAME, [BODY])
     Autoconf macros are defined using the ‘AC_DEFUN’ macro, which is
     similar to the M4 builtin ‘m4_define’ macro; this creates a macro
     named NAME and with BODY as its expansion.  In addition to defining
     a macro, ‘AC_DEFUN’ adds to it some code that is used to constrain
     the order in which macros are called, while avoiding redundant
     output (*note Prerequisite Macros::).

   An Autoconf macro definition looks like this:

     AC_DEFUN(MACRO-NAME, MACRO-BODY)

   You can refer to any arguments passed to the macro as ‘$1’, ‘$2’,
etc.  *Note How to define new macros: (m4)Definitions, for more complete
information on writing M4 macros.

   Most macros fall in one of two general categories.  The first
category includes macros which take arguments, in order to generate
output parameterized by those arguments.  Macros in this category are
designed to be directly expanded, often multiple times, and should not
be used as the argument to ‘AC_REQUIRE’.  The other category includes
macros which are shorthand for a fixed block of text, and therefore do
not take arguments.  For this category of macros, directly expanding the
macro multiple times results in redundant output, so it is more common
to use the macro as the argument to ‘AC_REQUIRE’, or to declare the
macro with ‘AC_DEFUN_ONCE’ (*note One-Shot Macros::).

   Be sure to properly quote both the MACRO-BODY _and_ the MACRO-NAME to
avoid any problems if the macro happens to have been previously defined.

   Each macro should have a header comment that gives its prototype, and
a brief description.  When arguments have default values, display them
in the prototype.  For example:

     # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
     # --------------------------------------
     m4_define([AC_MSG_ERROR],
       [{ AS_MESSAGE([error: $1], [2])
          exit m4_default([$2], [1]); }])

   Comments about the macro should be left in the header comment.  Most
other comments make their way into ‘configure’, so just keep using ‘#’
to introduce comments.

   If you have some special comments about pure M4 code, comments that
make no sense in ‘configure’ and in the header comment, then use the
builtin ‘dnl’: it causes M4 to discard the text through the next
newline.

   Keep in mind that ‘dnl’ is rarely needed to introduce comments; ‘dnl’
is more useful to get rid of the newlines following macros that produce
no output, such as ‘AC_REQUIRE’.

   Public third-party macros need to use ‘AC_DEFUN’, and not
‘m4_define’, in order to be found by ‘aclocal’ (*note
(automake)Extending aclocal::).  Additionally, if it is ever determined
that a macro should be made obsolete, it is easy to convert from
‘AC_DEFUN’ to ‘AU_DEFUN’ in order to have ‘autoupdate’ assist the user
in choosing a better alternative, but there is no corresponding way to
make ‘m4_define’ issue an upgrade notice (*note AU_DEFUN::).

   There is another subtle, but important, difference between using
‘m4_define’ and ‘AC_DEFUN’: only the former is unaffected by
‘AC_REQUIRE’.  When writing a file, it is always safe to replace a block
of text with a ‘m4_define’ macro that will expand to the same text.  But
replacing a block of text with an ‘AC_DEFUN’ macro with the same content
does not necessarily give the same results, because it changes the
location where any embedded but unsatisfied ‘AC_REQUIRE’ invocations
within the block will be expanded.  For an example of this, see *note
Expanded Before Required::.