Go to the first, previous, next, last section, table of contents.

Writing Tests

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.

Examining Declarations

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.

Macro: AC_TRY_CPP (includes, [action-if-true [, action-if-false]])
includes is C or C++ #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.

Macro: AC_EGREP_HEADER (pattern, header-file, action-if-found [, action-if-not-found])
If the output of running the preprocessor on the system header file header-file matches the 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)

Macro: AC_EGREP_CPP (pattern, program, [action-if-found [, action-if-not-found]])
program is the text of a C or C++ program, on which shell variable, backquote, and backslash substitutions are performed. If the output of running the preprocessor on program matches the 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.

Examining Syntax

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.

Macro: AC_TRY_COMPILE (includes, function-body, [action-if-found [, action-if-not-found]])
Create a test C program to see whether a function whose body consists of function-body can be compiled; includes is any #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).

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.

Macro: AC_TRY_LINK (includes, function-body, [action-if-found [, action-if-not-found]])
Create a test C program to see whether a function whose body consists of function-body can be compiled and linked; includes is any #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.

Macro: AC_COMPILE_CHECK (echo-text, includes, function-body, action-if-found [, action-if-not-found])
This is an obsolete version of 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).

Checking Run Time Behavior

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.

Running Test Programs

Use the following macro if you need to test run-time behavior of the system while configuring.

Macro: AC_TRY_RUN (program, [action-if-true [, action-if-false [, action-if-cross-compiling]]])
program is the text of a C program, on which shell variable and backquote substitutions are performed. If it compiles and links successfully and returns an exit status of 0 when executed, run shell commands action-if-true. Otherwise run shell commands action-if-false; the exit status of the program is available in the shell variable `$?'. This macro uses 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.

Macro: AC_C_CROSS
If the C compiler being used does not produce executables that can run on the system where configure is being run, set the shell variable cross_compiling to `yes', otherwise `no'.

Guidelines for Test Programs

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.

Test Functions

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).

Portable Shell Programming

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.

Testing Values and Files

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}

Multiple Cases

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)

Language Choice

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'.

Macro: AC_LANG_C
Do compilation tests using CC and CPP and use extension `.c' for test programs.

Macro: AC_LANG_CPLUSPLUS
Do compilation tests using CXX and CXXCPP and use extension `.C' for test programs.

Macro: AC_LANG_SAVE
Remember the current language (as set by 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.

Macro: AC_LANG_RESTORE
Select the language that is saved on the top of the stack, as set by 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.

Macro: AC_REQUIRE_CPP
Ensure that whichever preprocessor would currently be used for tests has been found. Calls AC_REQUIRE (see section Prerequisite Macros) with an argument of either AC_PROG_CPP or AC_PROG_CXXCPP, depending on which language is current.


Go to the first, previous, next, last section, table of contents.