autoconf: Macro Names

1 
1 10.2 Macro Names
1 ================
1 
1 All of the public Autoconf macros have all-uppercase names in the
1 namespace `^AC_' to prevent them from accidentally conflicting with
1 other text; Autoconf also reserves the namespace `^_AC_' for internal
1 macros.  All shell variables that they use for internal purposes have
1 mostly-lowercase names starting with `ac_'.  Autoconf also uses
1 here-document delimiters in the namespace `^_AC[A-Z]'.  During
1 `configure', files produced by Autoconf make heavy use of the file
1 system namespace `^conf'.
1 
11    Since Autoconf is built on top of M4sugar (⇒Programming in
 M4sugar) and M4sh (⇒Programming in M4sh), you must also be
1 aware of those namespaces (`^_?\(m4\|AS\)_').  And since `configure.ac'
1 is also designed to be scanned by Autoheader, Autoscan, Autoupdate, and
1 Automake, you should be aware of the `^_?A[HNUM]_' namespaces.  In
1 general, you _should not use_ the namespace of a package that does not
1 own the macro or shell code you are writing.
1 
1    To ensure that your macros don't conflict with present or future
1 Autoconf macros, you should prefix your own macro names and any shell
1 variables they use with some other sequence.  Possibilities include your
1 initials, or an abbreviation for the name of your organization or
1 software package.  Historically, people have not always followed the
1 rule of using a namespace appropriate for their package, and this has
1 made it difficult for determining the origin of a macro (and where to
1 report bugs about that macro), as well as difficult for the true
1 namespace owner to add new macros without interference from pre-existing
1 uses of third-party macros.  Perhaps the best example of this confusion
1 is the `AM_GNU_GETTEXT' macro, which belongs, not to Automake, but to
1 Gettext.
1 
1    Most of the Autoconf macros' names follow a structured naming
1 convention that indicates the kind of feature check by the name.  The
1 macro names consist of several words, separated by underscores, going
1 from most general to most specific.  The names of their cache variables
1 use the same convention (⇒Cache Variable Names, for more
1 information on them).
1 
1    The first word of the name after the namespace initials (such as
1 `AC_') usually tells the category of the feature being tested.  Here
1 are the categories used in Autoconf for specific test macros, the kind
1 of macro that you are more likely to write.  They are also used for
1 cache variables, in all-lowercase.  Use them where applicable; where
1 they're not, invent your own categories.
1 
1 `C'
1      C language builtin features.
1 
1 `DECL'
1      Declarations of C variables in header files.
1 
1 `FUNC'
1      Functions in libraries.
1 
1 `GROUP'
1      Posix group owners of files.
1 
1 `HEADER'
1      Header files.
1 
1 `LIB'
1      C libraries.
1 
1 `PROG'
1      The base names of programs.
1 
1 `MEMBER'
1      Members of aggregates.
1 
1 `SYS'
1      Operating system features.
1 
1 `TYPE'
1      C builtin or declared types.
1 
1 `VAR'
1      C variables in libraries.
1 
1    After the category comes the name of the particular feature being
1 tested.  Any further words in the macro name indicate particular aspects
1 of the feature.  For example, `AC_PROG_CC_STDC' checks whether the C
1 compiler supports ISO Standard C.
1 
1    An internal macro should have a name that starts with an underscore;
1 Autoconf internals should therefore start with `_AC_'.  Additionally, a
1 macro that is an internal subroutine of another macro should have a
1 name that starts with an underscore and the name of that other macro,
1 followed by one or more words saying what the internal macro does.  For
1 example, `AC_PATH_X' has internal macros `_AC_PATH_X_XMKMF' and
1 `_AC_PATH_X_DIRECT'.
1