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

10.2 Macro Names
================

All of the public Autoconf macros have all-uppercase names in the
namespace ‘^AC_’ to prevent them from accidentally conflicting with
other text; Autoconf also reserves the namespace ‘^_AC_’ for internal
macros.  All shell variables that they use for internal purposes have
mostly-lowercase names starting with ‘ac_’.  Autoconf also uses
here-document delimiters in the namespace ‘^_AC[A-Z]’.  During
‘configure’, files produced by Autoconf make heavy use of the file
system namespace ‘^conf’.

   Since Autoconf is built on top of M4sugar (*note Programming in
M4sugar::) and M4sh (*note Programming in M4sh::), you must also be
aware of those namespaces (‘^_?\(m4\|AS\)_’).  And since ‘configure.ac’
is also designed to be scanned by Autoheader, Autoscan, Autoupdate, and
Automake, you should be aware of the ‘^_?A[HNUM]_’ namespaces.  In
general, you _should not use_ the namespace of a package that does not
own the macro or shell code you are writing.

   To ensure that your macros don't conflict with present or future
Autoconf macros, you should prefix your own macro names and any shell
variables they use with some other sequence.  Possibilities include your
initials, or an abbreviation for the name of your organization or
software package.  Historically, people have not always followed the
rule of using a namespace appropriate for their package, and this has
made it difficult for determining the origin of a macro (and where to
report bugs about that macro), as well as difficult for the true
namespace owner to add new macros without interference from pre-existing
uses of third-party macros.  Perhaps the best example of this confusion
is the ‘AM_GNU_GETTEXT’ macro, which belongs, not to Automake, but to
Gettext.

   Most of the Autoconf macros' names follow a structured naming
convention that indicates the kind of feature check by the name.  The
macro names consist of several words, separated by underscores, going
from most general to most specific.  The names of their cache variables
use the same convention (*note Cache Variable Names::, for more
information on them).

   The first word of the name after the namespace initials (such as
‘AC_’) usually tells the category of the feature being tested.  Here are
the categories used in Autoconf for specific test macros, the kind of
macro that you are more likely to write.  They are also used for cache
variables, in all-lowercase.  Use them where applicable; where they're
not, invent your own categories.

‘C’
     C language builtin features.
‘DECL’
     Declarations of C variables in header files.
‘FUNC’
     Functions in libraries.
‘GROUP’
     Posix group owners of files.
‘HEADER’
     Header files.
‘LIB’
     C libraries.
‘PROG’
     The base names of programs.
‘MEMBER’
     Members of aggregates.
‘SYS’
     Operating system features.
‘TYPE’
     C builtin or declared types.
‘VAR’
     C variables in libraries.

   After the category comes the name of the particular feature being
tested.  Any further words in the macro name indicate particular aspects
of the feature.  For example, ‘AC_PROG_MAKE_SET’ checks whether ‘make’
sets a variable to its own name.

   An internal macro should have a name that starts with an underscore;
Autoconf internals should therefore start with ‘_AC_’.  Additionally, a
macro that is an internal subroutine of another macro should have a name
that starts with an underscore and the name of that other macro,
followed by one or more words saying what the internal macro does.  For
example, ‘AC_PATH_X’ has internal macros ‘_AC_PATH_X_XMKMF’ and
‘_AC_PATH_X_DIRECT’.