If the existing feature tests don't do something you need, you have to write new ones. These macros are the building blocks. They provide ways for other macros to check whether various kinds of features are available and report the results.
This chapter contains some suggestions and some of the reasons why the existing tests are written the way they are. You can also learn a lot about how to write Autoconf tests by looking at the existing ones. If something goes wrong in one or more of the Autoconf tests, this information can help you understand the assumptions behind them, which might help you figure out how to best solve the problem.
These macros check the output of the C compiler system. They do not cache the results of their tests for future use (see section Caching Results), because they don't know enough about the information they are checking for to generate a cache variable name. They also do not print any messages, for the same reason. The checks for particular kinds of C features call these macros and do cache their results and print messages about what they're checking for.
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. See section Writing Macros, for how to do that.
The macro AC_TRY_CPP is used to check whether particular header
files exist. You can check for one at a time, or more than one if you
need several header files to all exist for some purpose.
#include statements and declarations,
on which shell variable, backquote, and backslash substitutions are
performed. (Actually, it can be any C program, but other statements are
probably not useful.) If the preprocessor produces no error messages
while processing it, run shell commands action-if-true. Otherwise
run shell commands action-if-false.
This macro uses CPPFLAGS, but not CFLAGS, because
`-g', `-O', etc. are not valid options to many C
preprocessors.
Here is now to find out whether a header file contains a particular
declaration, such as a typedef, a structure, a structure member, or a
function. Use AC_EGREP_HEADER instead of running grep
directly on the header file; on some systems the symbol might be defined
in another header file that the file you are checking `#include's.
egrep regular expression
pattern, execute shell commands action-if-found, otherwise
execute action-if-not-found.
To check for C preprocessor symbols, either defined by header files or
predefined by the C preprocessor, use AC_EGREP_CPP. Here is an
example of the latter:
AC_EGREP_CPP(yes, [#ifdef _AIX yes #endif ], is_aix=yes, is_aix=no)
egrep regular expression pattern, execute shell commands
action-if-found, otherwise execute action-if-not-found.
This macro calls AC_PROG_CPP or AC_PROG_CXXCPP (depending
on which language is current, see section Language Choice), if it hasn't
been called already.
To check for a syntax feature of the C or C++ compiler, such as whether
it recognizes a certain keyword, use AC_TRY_COMPILE to try to
compile a small program that uses that feature. You can also use it to
check for structures and structure members that are not present on all
systems.
#include statements needed by the code in function-body.
If the file compiles successfully, run shell commands
action-if-found, otherwise run action-if-not-found. This
macro uses CFLAGS or CXXFLAGS, and CPPFLAGS, when
compiling. It does not try to link; use AC_TRY_LINK if you need
to do that (see section Examining Libraries).
To check for a library, a function, or a global variable, Autoconf
configure scripts try to compile and link a small program that
uses it. This is unlike Metaconfig, which by default uses nm
or ar on the C library to try to figure out which functions are
available. Trying to link with the function is usually a more reliable
approach because it avoids dealing with the variations in the options
and output formats of nm and ar and in the location of the
standard libraries. It also allows configuring for cross-compilation or
checking a function's runtime behavior if needed. On the other hand, it
can be slower than scanning the libraries once.
A few systems have linkers that do not return a failure exit status when
there are unresolved functions in the link. This bug makes the
configuration scripts produced by Autoconf unusable on those systems.
However, some of them can be given options that make the exit status
correct. This is a problem that Autoconf does not currently handle
automatically. If users encounter this problem, they might be able to
solve it by setting LDFLAGS in the environment to pass whatever
options the linker needs (for example, `-Wl,-dn' on MIPS RISC/OS).
AC_TRY_LINK is used to compile test programs to test for
functions and global variables. It is also used (by
AC_CHECK_LIB) to check for libraries, by adding the library being
checked for to LIBS temporarily and trying to link a small
program.
#include statements needed by the code in function-body.
If the file compiles and links successfully, run shell commands
action-if-found, otherwise run action-if-not-found. This
macro uses CFLAGS or CXXFLAGS, CPPFLAGS,
LDFLAGS, and LIBS when compiling.
AC_TRY_LINK, with the addition that it
prints `checking for echo-text' to the standard output first,
if echo-text is non-empty. Use AC_MSG_CHECKING and
AC_MSG_RESULT instead to print messages (see section Printing Messages).
Sometimes you need to find out how a system performs at run time, such as whether a given function has a certain capability or bug. If you can, make such checks when your program runs instead of when it is configured. You can check for things like the machine's endianness when your program initializes itself.
If you really need to test for a run-time behavior while configuring,
you can write a test program to determine the result, and compile and
run it using AC_TRY_RUN. Avoid running test programs if
possible, because using them prevents people from configuring your
package for cross-compiling.
Use the following macro if you need to test run-time behavior of the system while configuring.
CFLAGS or
CXXFLAGS, CPPFLAGS, LDFLAGS, and LIBS when
compiling.
If the C compiler being used does not produce executables that run on
the system where configure is being run, then the test program is
not run. If the optional shell commands action-if-cross-compiling
are given, they are run instead and this macro calls AC_C_CROSS
if it has not already been called. Otherwise, configure prints
an error message and exits.
Try to provide a pessimistic default value to use when cross-compiling
makes run-time tests impossible. You do this by passing the optional
last argument to AC_TRY_RUN. autoconf prints a warning
message when creating configure each time it encounters a call to
AC_TRY_RUN with no action-if-cross-compiling argument
given. You may ignore the warning, though users will not be able to
configure your package for cross-compiling. A few of the macros
distributed with Autoconf produce this warning message.
To configure for cross-compiling you can also choose a value for those parameters based on the canonical system name (see section Manual Configuration). Alternatively, set up a test results cache file with the correct values for the target system (see section Caching Results).
To provide a default for calls of AC_TRY_RUN that are embedded in
other macros, including a few of the ones that come with Autoconf, you
can call AC_C_CROSS before running them. Then, if the shell
variable cross_compiling is set to `yes', use an alternate
method to get the results instead of calling the macros.
configure is being run, set the shell
variable cross_compiling to `yes', otherwise `no'.
Test programs should not write anything to the standard output. They
should return 0 if the test succeeds, nonzero otherwise, so that success
can be distinguished easily from a core dump or other failure;
segmentation violations and other failures produce a nonzero exit
status. Test programs should exit, not return, from
main, because on some systems (old Suns, at least) the argument
to return in main is ignored.
Test programs can use #if or #ifdef to check the values of
preprocessor macros defined by tests that have already run. For
example, if you call AC_HEADER_STDC, then later on in
`configure.in' you can have a test program that includes an ANSI C
header file conditionally:
#if STDC_HEADERS # include <stdlib.h> #endif
If a test program needs to use or create a data file, give it a name
that starts with `conftest', such as `conftestdata'. The
configure script cleans up by running `rm -rf conftest*'
after running test programs and if the script is interrupted.
Function declarations in test programs should have a prototype conditionalized for C++. In practice, though, test programs rarely need functions that take arguments.
#ifdef __cplusplus foo(int i) #else foo(i) int i; #endif
Functions that test programs declare should also be conditionalized for C++, which requires `extern "C"' prototypes. Make sure to not include any header files containing clashing prototypes.
#ifdef __cplusplus extern "C" void *malloc(size_t); #else char *malloc(); #endif
If a test program calls a function with invalid parameters (just to see
whether it exists), organize the program to ensure that it never invokes
that function. You can do this by calling it in another function that is
never invoked. You can't do it by putting it after a call to
exit, because GCC version 2 knows that exit never returns
and optimizes out any code that follows it in the same block.
If you include any header files, make sure to call the functions
relevant to them with the correct number of arguments, even if they are
just 0, to avoid compilation errors due to prototypes. GCC version 2
has internal prototypes for several functions that it automatically
inlines; for example, memcpy. To avoid errors when checking for
them, either pass them the correct number of arguments or redeclare them
with a different return type (such as char).
When writing your own checks, there are some shell script programming
techniques you should avoid in order to make your code portable. The
Bourne shell and upward-compatible shells like Bash and the Korn shell
have evolved over the years, but to prevent trouble, do not take
advantage of features that were added after UNIX version 7, circa 1977.
You should not use shell functions, aliases, negated character classes,
or other features that are not found in all Bourne-compatible shells;
restrict yourself to the lowest common denominator. Even unset
is not supported by all shells! Also, include a space after the
exclamation point in interpreter specifications, like this:
#! /usr/bin/perl
If you omit the space before the path, then 4.2BSD based systems (such as Sequent DYNIX) will ignore the line, because they interpret `#! /' as a 4-byte magic number.
The set of external programs you should run in a configure script
is fairly small. See section `Utilities in Makefiles' in GNU Coding Standards, for the list. This
restriction allows users to start out with a fairly small set of
programs and build the rest, avoiding too many interdependencies between
packages.
Some of these external utilities have a portable subset of features, as
well; for example, don't rely on ln having a `-f' option or
cat having any options. sed scripts should not contain
comments or use branch labels longer than 8 characters. Don't use
`grep -s' to suppress output, because `grep -s' on System V
does not suppress output, only error messages. Instead, redirect the
standard output and standard error (in case the file doesn't exist) of
grep to `/dev/null'. Check the exit status of grep
to determine whether it found a match.
configure scripts need to test properties of many files and
strings. Here are some portability problems to watch out for when doing
those tests.
The test program is the way to perform many file and string
tests. It is often invoked by the alternate name `[', but using
that name in Autoconf code is asking for trouble since it is an
m4 quote character.
If you need to make multiple checks using test, combine
them with the shell operators `&&' and `||' instead of using
the test operators `-a' and `-o'. On System V, the
precedence of `-a' and `-o' is wrong relative to the unary
operators; consequently, POSIX does not specify them, so using them is
nonportable. If you combine `&&' and `||' in the same
statement, keep in mind that they have equal precedence.
To enable configure scripts to support cross-compilation, they
shouldn't do anything that tests features of the host system instead of
the target system. But occasionally you may find it necessary to check
whether some arbitrary file exists. To do so, use `test -f' or
`test -r'. Do not use `test -x', because 4.3BSD does not have
it.
Another nonportable shell programming construction is
var=${var:-value}
The intent is to set var to value only if it is not already
set, but if var has any value, even the empty string, to leave it
alone. Old BSD shells, including the Ultrix sh, don't accept
the colon, and complain and die. A portable equivalent is
: ${var=value}
Some operations are accomplished in several possible ways, depending on the UNIX variant. Checking for them essentially requires a "case statement". Autoconf does not directly provide one; however, it is easy to simulate by using a shell variable to keep track of whether a way to perform the operation has been found yet.
Here is an example that uses the shell variable fstype to keep
track of whether the remaining cases need to be checked.
AC_MSG_CHECKING(how to get filesystem type) fstype=no # The order of these tests is important. AC_TRY_CPP([#include <sys/statvfs.h> #include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4) if test $fstype = no; then AC_TRY_CPP([#include <sys/statfs.h> #include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3) fi if test $fstype = no; then AC_TRY_CPP([#include <sys/statfs.h> #include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX) fi # (more cases omitted here) AC_MSG_RESULT($fstype)
Packages that use both C and C++ need to test features of both
compilers. Autoconf-generated configure scripts check for C
features by default. The following macros determine which language's
compiler is used in tests that follow in `configure.in'.
CC and CPP and use extension
`.c' for test programs.
CXX and CXXCPP and use
extension `.C' for test programs.
AC_LANG_C or
AC_LANG_CPLUSPLUS) on a stack. Does not change which language is
current. Use this macro and AC_LANG_RESTORE in macros that need
to temporarily switch to a particular language.
AC_LANG_SAVE, and remove it from the stack. This macro is
equivalent to either AC_LANG_C or AC_LANG_CPLUSPLUS,
whichever had been run most recently when AC_LANG_SAVE was last
called.
Do not call this macro more times than AC_LANG_SAVE.
AC_REQUIRE (see section Prerequisite Macros) with an
argument of either AC_PROG_CPP or AC_PROG_CXXCPP,
depending on which language is current.