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 (see Programming in M4sugar) and M4sh (see 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 (see 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.