Go to the previous, next section.
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.
@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.
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
DECL
FUNC
GROUP
HEADER
LIB
PATH
PROG
STRUCT
SYS
TYPE
VAR
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.
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'.
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.
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])
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.
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.