Go to the previous, next section.

Writing Macros

When you write a feature test that could be applicable to more than one software package, the best thing to do is encapsulate it in a new macro. Here are some instructions and guidelines for writing Autoconf macros.

Macro Definitions

@maindex DEFUN Autoconf macros are defined using the AC_DEFUN macro, which is similar to the m4 builtin define macro. In addition to defining a macro, AC_DEFUN adds to it some code which is used to constrain the order in which macros are called (see section Prerequisite Macros).

An Autoconf macro definition looks like this:

AC_DEFUN(macro-name, [macro-body])

The square brackets here do not indicate optional text: they should literally be present in the macro definition to avoid macro expansion problems (see section Quoting). You can refer to any arguments passed to the macro as `$1', `$2', etc.

To introduce comments in m4, use the m4 builtin dnl; it causes m4 to discard the text through the next newline. It is not needed between macro definitions in `acsite.m4' and `aclocal.m4', because all output is discarded until AC_INIT is called.

See section `How to define new macros' in GNU m4, for more complete information on writing m4 macros.

Macro Names

All of the Autoconf macros have all-uppercase names starting with `AC_' to prevent them from accidentally conflicting with other text. All shell variables that they use for internal purposes have mostly-lowercase names starting with `ac_'. 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.

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 section Cache Variable Names, for more information on them).

The first word of the name after `AC_' usually tells the category of 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
UNIX group owners of files.
HEADER
Header files.
LIB
C libraries.
PATH
The full path names to files, including programs.
PROG
The base names of programs.
STRUCT
Definitions of C structures in header files.
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_FUNC_UTIME_NULL checks the behavior of the utime function when called with a NULL pointer.

A macro that is an internal subroutine of another macro should have a name that starts with 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.

Quoting

Macros that are called by other macros are evaluated by m4 several times; each evaluation might require another layer of quotes to prevent unwanted expansions of macros or m4 builtins, such as `define' and `$1'. Quotes are also required around macro arguments that contain commas, since commas separate the arguments from each other. It's a good idea to quote any macro arguments that contain newlines or calls to other macros, as well.

Autoconf changes the m4 quote characters from the default ``' and `'' to `[' and `]', because many of the macros use ``' and `'', mismatched. However, in a few places the macros need to use brackets (usually in C program text or regular expressions). In those places, they use the m4 builtin command changequote to temporarily change the quote characters to `<<' and `>>'. (Sometimes, if they don't need to quote anything, they disable quoting entirely instead by setting the quote characters to empty strings.) Here is an example:

AC_TRY_LINK(
changequote(<<, >>)dnl
<<#include <time.h>
#ifndef tzname /* For SGI.  */
extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
#endif>>,
changequote([, ])dnl
[atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)

When you create a configure script using newly written macros, examine it carefully to check whether you need to add more quotes in your macros. If one or more words have disappeared in the m4 output, you need more quotes. When in doubt, quote.

However, it's also possible to put on too many layers of quotes. If this happens, the resulting configure script will contain unexpanded macros. The autoconf program checks for this problem by doing `grep AC_ configure'.

Dependencies Between Macros

Some Autoconf macros depend on other macros having been called first in order to work correctly. Autoconf provides a way to ensure that certain macros are called if needed and a way to warn the user if macros are called in an order that might cause incorrect operation.

Prerequisite Macros

A macro that you write might need to use values that have previously been computed by other macros. For example, AC_DECL_YYTEXT examines the output of flex or lex, so it depends on AC_PROG_LEX having been called first to set the shell variable LEX.

Rather than forcing the user of the macros to keep track of the dependencies between them, you can use the AC_REQUIRE macro to do it automatically. AC_REQUIRE can ensure that a macro is only called if it is needed, and only called once.

Macro: AC_REQUIRE (macro-name)

@maindex REQUIRE If the m4 macro macro-name has not already been called, call it (without any arguments). Make sure to quote macro-name with square brackets. macro-name must have been defined using AC_DEFUN or else contain a call to AC_PROVIDE to indicate that it has been called.

An alternative to using AC_DEFUN is to use define and call AC_PROVIDE. Because this technique does not prevent nested messages, it is considered obsolete.

Macro: AC_PROVIDE (this-macro-name)

@maindex PROVIDE Record the fact that this-macro-name has been called. this-macro-name should be the name of the macro that is calling AC_PROVIDE. An easy way to get it is from the m4 builtin variable $0, like this:

AC_PROVIDE([$0])

Suggested Ordering

Some macros should be run before another macro if both are called, but neither requires that the other be called. For example, a macro that changes the behavior of the C compiler should be called before any macros that run the C compiler. Many of these dependencies are noted in the documentation.

Autoconf provides the AC_BEFORE macro to warn users when macros with this kind of dependency appear out of order in a `configure.in' file. The warning occurs when creating configure from `configure.in', not when running configure. For example, AC_PROG_CPP checks whether the C compiler can run the C preprocessor when given the `-E' option. It should therefore be called after any macros that change which C compiler is being used, such as AC_PROG_CC. So AC_PROG_CC contains:

AC_BEFORE([$0], [AC_PROG_CPP])dnl

This warns the user if a call to AC_PROG_CPP has already occurred when AC_PROG_CC is called.

Macro: AC_BEFORE (this-macro-name, called-macro-name)

@maindex BEFORE Make m4 print a warning message on the standard error output if called-macro-name has already been called. this-macro-name should be the name of the macro that is calling AC_BEFORE. The macro called-macro-name must have been defined using AC_DEFUN or else contain a call to AC_PROVIDE to indicate that it has been called.

Obsolete Macros

Configuration and portability technology has evolved over the years. Often better ways of solving a particular problem are developed, or ad-hoc approaches are systematized. This process has occurred in many parts of Autoconf. One result is that some of the macros are now considered obsolete; they still work, but are no longer considered the best thing to do. Autoconf provides the AC_OBSOLETE macro to warn users producing configure scripts when they use obsolete macros, to encourage them to modernize. A sample call is:

AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl

Macro: AC_OBSOLETE (this-macro-name [, suggestion])

@maindex OBSOLETE Make m4 print a message on the standard error output warning that this-macro-name is obsolete, and giving the file and line number where it was called. this-macro-name should be the name of the macro that is calling AC_OBSOLETE. If suggestion is given, it is printed at the end of the warning message; for example, it can be a suggestion for what to use instead of this-macro-name.

Go to the previous, next section.