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