Autoconf

3.1.1 A Shell Script Compiler

Just as for any other computer language, in order to properly program configure.ac in Autoconf you must understand what problem the language tries to address and how it does so.

The problem Autoconf addresses is that the world is a mess. After all, you are using Autoconf in order to have your package compile easily on all sorts of different systems, some of them being extremely hostile. Autoconf itself bears the price for these differences: configure must run on all those systems, and thus configure must limit itself to their lowest common denominator of features.

Naturally, you might then think of shell scripts; who needs autoconf? A set of properly written shell functions is enough to make it easy to write configure scripts by hand. Sigh! Unfortunately, even in 2008, where shells without any function support are far and few between, there are pitfalls to avoid when making use of them. Also, finding a Bourne shell that accepts shell functions is not trivial, even though there is almost always one on interesting porting targets.

So, what is really needed is some kind of compiler, autoconf, that takes an Autoconf program, configure.ac, and transforms it into a portable shell script, configure.

How does autoconf perform this task?

There are two obvious possibilities: creating a brand new language or extending an existing one. The former option is attractive: all sorts of optimizations could easily be implemented in the compiler and many rigorous checks could be performed on the Autoconf program (e.g., rejecting any non-portable construct). Alternatively, you can extend an existing language, such as the sh (Bourne shell) language.

Autoconf does the latter: it is a layer on top of sh. It was therefore most convenient to implement autoconf as a macro expander: a program that repeatedly performs macro expansions on text input, replacing macro calls with macro bodies and producing a pure sh script in the end. Instead of implementing a dedicated Autoconf macro expander, it is natural to use an existing general-purpose macro language, such as M4, and implement the extensions as a set of M4 macros.

3.1.2 The Autoconf Language

The Autoconf language differs from many other computer languages because it treats actual code the same as plain text. Whereas in C, for instance, data and instructions have different syntactic status, in Autoconf their status is rigorously the same. Therefore, we need a means to distinguish literal strings from text to be expanded: quotation.

When calling macros that take arguments, there must not be any white space between the macro name and the open parenthesis.

AC_INIT ([oops], [1.0]) # incorrect
AC_INIT([hello], [1.0]) # good

Arguments should be enclosed within the quote characters ‘[’ and ‘]’, and be separated by commas. Any leading blanks or newlines in arguments are ignored, unless they are quoted. You should always quote an argument that might contain a macro name, comma, parenthesis, or a leading blank or newline. This rule applies recursively for every macro call, including macros called from other macros. For more details on quoting rules, see Programming in M4.

For instance:

AC_CHECK_HEADER([stdio.h],
                [AC_DEFINE([HAVE_STDIO_H], [1],
                   [Define to 1 if you have <stdio.h>.])],
                [AC_MSG_ERROR([sorry, can't do anything for you])])

is quoted properly. You may safely simplify its quotation to:

AC_CHECK_HEADER([stdio.h],
                [AC_DEFINE([HAVE_STDIO_H], 1,
                   [Define to 1 if you have <stdio.h>.])],
                [AC_MSG_ERROR([sorry, can't do anything for you])])

because ‘1’ cannot contain a macro call. Here, the argument of AC_MSG_ERROR must be quoted; otherwise, its comma would be interpreted as an argument separator. Also, the second and third arguments of ‘AC_CHECK_HEADER’ must be quoted, since they contain macro calls. The three arguments ‘HAVE_STDIO_H’, ‘stdio.h’, and ‘Define to 1 if you have <stdio.h>.’ do not need quoting, but if you unwisely defined a macro with a name like ‘Define’ or ‘stdio’ then they would need quoting. Cautious Autoconf users would keep the quotes, but many Autoconf users find such precautions annoying, and would rewrite the example as follows:

AC_CHECK_HEADER(stdio.h,
                [AC_DEFINE(HAVE_STDIO_H, 1,
                   [Define to 1 if you have <stdio.h>.])],
                [AC_MSG_ERROR([sorry, can't do anything for you])])

This is safe, so long as you adopt good naming conventions and do not define macros with names like ‘HAVE_STDIO_H’, ‘stdio’, or ‘h’. Though it is also safe here to omit the quotes around ‘Define to 1 if you have <stdio.h>.’ this is not recommended, as message strings are more likely to inadvertently contain commas.

The following example is wrong and dangerous, as it is underquoted:

AC_CHECK_HEADER(stdio.h,
                AC_DEFINE(HAVE_STDIO_H, 1,
                   Define to 1 if you have <stdio.h>.),
                AC_MSG_ERROR([sorry, can't do anything for you]))

In other cases, you may want to use text that also resembles a macro call. You must quote that text (whether just the potential problem, or the entire line) even when it is not passed as a macro argument; and you may also have to use m4_pattern_allow (see Forbidden Patterns), to declare your intention that the resulting configure file will have a literal that resembles what would otherwise be reserved for a macro name. For example:

dnl Simulate a possible future autoconf macro
m4_define([AC_DC], [oops])
dnl Underquoted:
echo "Hard rock was here!  --AC_DC"
dnl Correctly quoted:
m4_pattern_allow([AC_DC])
echo "Hard rock was here!  --[AC_DC]"
[echo "Hard rock was here!  --AC_DC"]

which results in this text in configure:

echo "Hard rock was here!  --oops"
echo "Hard rock was here!  --AC_DC"
echo "Hard rock was here!  --AC_DC"

When you use the same text in a macro argument, you must therefore have an extra quotation level (since one is stripped away by the macro substitution). In general, then, it is a good idea to use double quoting for all literal string arguments, either around just the problematic portions, or over the entire argument:

m4_pattern_allow([AC_DC])
AC_MSG_WARN([[AC_DC] stinks  --Iron Maiden])
AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])

It is also possible to avoid the problematic patterns in the first place, by the use of additional escaping (either a quadrigraph, or creative shell constructs), in which case it is no longer necessary to use m4_pattern_allow:

echo "Hard rock was here!  --AC""_DC"
AC_MSG_WARN([[AC@&t@_DC stinks  --Iron Maiden]])

You are now able to understand one of the constructs of Autoconf that has been continually misunderstood... The rule of thumb is that whenever you expect macro expansion, expect quote expansion; i.e., expect one level of quotes to be lost. For instance:

AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [],
 [AC_MSG_ERROR([you lose])])

is incorrect: here, the first argument of AC_LANG_SOURCE is ‘char b[10];’ and is expanded once, which results in ‘char b10;’; and the AC_LANG_SOURCE is also expanded prior to being passed to AC_COMPILE_IFELSE. (There was an idiom common in Autoconf’s past to address this issue via the M4 changequote primitive, but do not use it!) Let’s take a closer look: the author meant the first argument to be understood as a literal, and therefore it must be quoted twice; likewise, the intermediate AC_LANG_SOURCE macro should be quoted once so that it is only expanded after the rest of the body of AC_COMPILE_IFELSE is in place:

AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [],
  [AC_MSG_ERROR([you lose])])

Voilà, you actually produce ‘char b[10];’ this time!

On the other hand, descriptions (e.g., the last parameter of AC_DEFINE or AS_HELP_STRING) are not literals—they are subject to line breaking, for example—and should not be double quoted. Even if these descriptions are short and are not actually broken, double quoting them yields weird results.

Some macros take optional arguments, which this documentation represents as [arg] (not to be confused with the quote characters). You may just leave them empty, or use ‘[]’ to make the emptiness of the argument explicit, or you may simply omit the trailing commas. The three lines below are equivalent:

AC_CHECK_HEADERS([stdio.h], [], [], [])
AC_CHECK_HEADERS([stdio.h],,,)
AC_CHECK_HEADERS([stdio.h])

It is best to put each macro call on its own line in configure.ac. Most of the macros don’t add extra newlines; they rely on the newline after the macro call to terminate the commands. This approach makes the generated configure script a little easier to read by not inserting lots of blank lines. It is generally safe to set shell variables on the same line as a macro call, because the shell allows assignments without intervening newlines.

You can include comments in configure.ac files by starting them with the ‘#’. For example, it is helpful to begin configure.ac files with a line like this:

# Process this file with autoconf to produce a configure script.

3.1.3 Standard configure.ac Layout

The order in which configure.ac calls the Autoconf macros is not important, with a few exceptions. Every configure.ac must contain a call to AC_INIT before the checks, and a call to AC_OUTPUT at the end (see Outputting Files). Additionally, some macros rely on other macros having been called first, because they check previously set values of some variables to decide what to do. These macros are noted in the individual descriptions (see Existing Tests), and they also warn you when configure is created if they are called out of order.

To encourage consistency, here is a suggested order for calling the Autoconf macros. Generally speaking, the things near the end of this list are those that could depend on things earlier in it. For example, library functions could be affected by types and libraries.

Autoconf requirements
AC_INIT(package, version, bug-report-address)
information on the package
checks for programs
checks for libraries
checks for header files
checks for types
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
AC_CONFIG_FILES([file…])
AC_OUTPUT

4.8.1 Preset Output Variables

Some output variables are preset by the Autoconf macros. Some of the Autoconf macros set additional output variables, which are mentioned in the descriptions for those macros. See Output Variable Index, for a complete list of output variables. See Installation Directory Variables, for the list of the preset ones related to installation directories. Below are listed the other preset ones, many of which are precious variables (see Setting Output Variables, AC_ARG_VAR).

The preset variables which are available during config.status (see Performing Configuration Actions) may also be used during configure tests. For example, it is permissible to reference ‘$srcdir’ when constructing a list of directories to pass via the -I option during a compiler feature check. When used in this manner, coupled with the fact that configure is always run from the top build directory, it is sufficient to use just ‘$srcdir’ instead of ‘$top_srcdir’.

Variable: CFLAGS ¶

Debugging and optimization options for the C compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_CC (or empty if you don’t). configure uses this variable when compiling or linking programs to test for C features.

If a compiler option affects only the behavior of the preprocessor (e.g., -Dname), it should be put into CPPFLAGS instead. If it affects only the linker (e.g., -Ldirectory), it should be put into LDFLAGS instead. If it affects only the compiler proper, CFLAGS is the natural home for it. If an option affects multiple phases of the compiler, though, matters get tricky:

• If an option selects a 32-bit or 64-bit build on a bi-arch system, it must be put direcly into CC, e.g., CC='gcc -m64'. This is necessary for config.guess to work right.
• Otherwise one approach is to put the option into CC. Another is to put it into both CPPFLAGS and LDFLAGS, but not into CFLAGS.

However, remember that some Makefile variables are reserved by the GNU Coding Standards for the use of the “user”—the person building the package. For instance, CFLAGS is one such variable.

Sometimes package developers are tempted to set user variables such as CFLAGS because it appears to make their job easier. However, the package itself should never set a user variable, particularly not to include switches that are required for proper compilation of the package. Since these variables are documented as being for the package builder, that person rightfully expects to be able to override any of these variables at build time. If the package developer needs to add switches without interfering with the user, the proper way to do that is to introduce an additional variable. Automake makes this easy by introducing AM_CFLAGS (see Flag Variables Ordering in GNU Automake), but the concept is the same even if Automake is not used.

Variable: configure_input ¶

A comment saying that the file was generated automatically by configure and giving the name of the input file. AC_OUTPUT adds a comment line containing this variable to the top of every makefile it creates. For other files, you should reference this variable in a comment at the top of each input file. For example, an input shell script should begin like this:

#!/bin/sh
# @configure_input@

The presence of that line also reminds people editing the file that it needs to be processed by configure in order to be used.

Variable: CPPFLAGS ¶

Preprocessor options for the C, C++, Objective C, and Objective C++ preprocessors and compilers. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when preprocessing or compiling programs to test for C, C++, Objective C, and Objective C++ features.

This variable’s contents should contain options like -I, -D, and -U that affect only the behavior of the preprocessor. Please see the explanation of CFLAGS for what you can do if an option affects other phases of the compiler as well.

Currently, configure always links as part of a single invocation of the compiler that also preprocesses and compiles, so it uses this variable also when linking programs. However, it is unwise to depend on this behavior because the GNU Coding Standards do not require it and many packages do not use CPPFLAGS when linking programs.

See Special Characters in Output Variables, for limitations that CPPFLAGS might run into.

Variable: CXXFLAGS ¶

Debugging and optimization options for the C++ compiler. It acts like CFLAGS, but for C++ instead of C.

Variable: DEFS ¶

-D options to pass to the C compiler. If AC_CONFIG_HEADERS is called, configure replaces ‘@DEFS@’ with -DHAVE_CONFIG_H instead (see Configuration Header Files). This variable is not defined while configure is performing its tests, only when creating the output files. See Setting Output Variables, for how to check the results of previous tests.

Variable: ECHO_C ¶

Variable: ECHO_N ¶

Variable: ECHO_T ¶

How does one suppress the trailing newline from echo for question-answer message pairs? These variables provide a way:

echo $ECHO_N "And the winner is... $ECHO_C"
sleep 100000000000
echo "${ECHO_T}dead."

Some old and uncommon echo implementations offer no means to achieve this, in which case ECHO_T is set to tab. You might not want to use it.

Variable: ERLCFLAGS ¶

Debugging and optimization options for the Erlang compiler. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when compiling programs to test for Erlang features.

Variable: FCFLAGS ¶

Debugging and optimization options for the Fortran compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_FC (or empty if you don’t). configure uses this variable when compiling or linking programs to test for Fortran features.

Variable: FFLAGS ¶

Debugging and optimization options for the Fortran 77 compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_F77 (or empty if you don’t). configure uses this variable when compiling or linking programs to test for Fortran 77 features.

Variable: LDFLAGS ¶

Options for the linker. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when linking programs to test for C, C++, Objective C, Objective C++, Fortran, and Go features.

This variable’s contents should contain options like -s and -L that affect only the behavior of the linker. Please see the explanation of CFLAGS for what you can do if an option also affects other phases of the compiler.

Don’t use this variable to pass library names (-l) to the linker; use LIBS instead.

Variable: LIBS ¶

-l options to pass to the linker. The default value is empty, but some Autoconf macros may prepend extra libraries to this variable if those libraries are found and provide necessary functions, see Library Files. configure uses this variable when linking programs to test for C, C++, Objective C, Objective C++, Fortran, and Go features.

Variable: OBJCFLAGS ¶

Debugging and optimization options for the Objective C compiler. It acts like CFLAGS, but for Objective C instead of C.

Variable: OBJCXXFLAGS ¶

Debugging and optimization options for the Objective C++ compiler. It acts like CXXFLAGS, but for Objective C++ instead of C++.

Variable: GOFLAGS ¶

Debugging and optimization options for the Go compiler. It acts like CFLAGS, but for Go instead of C.

Variable: builddir ¶

Rigorously equal to ‘.’. Added for symmetry only.

Variable: abs_builddir ¶

Absolute name of builddir.

Variable: top_builddir ¶

The relative name of the top level of the current build tree. In the top-level directory, this is the same as builddir.

Variable: top_build_prefix ¶

The relative name of the top level of the current build tree with final slash if nonempty. This is the same as top_builddir, except that it contains zero or more runs of ../, so it should not be appended with a slash for concatenation. This helps for make implementations that otherwise do not treat ./file and file as equal in the top-level build directory.

Variable: abs_top_builddir ¶

Absolute name of top_builddir.

Variable: srcdir ¶

The name of the directory that contains the source code for that makefile.

Variable: abs_srcdir ¶

Absolute name of srcdir.

Variable: top_srcdir ¶

The name of the top-level source code directory for the package. In the top-level directory, this is the same as srcdir.

Variable: abs_top_srcdir ¶

Absolute name of top_srcdir.

4.8.2 Installation Directory Variables

The following variables specify the directories for package installation, see Variables for Installation Directories in The GNU Coding Standards, for more information. Each variable corresponds to an argument of configure; trailing slashes are stripped so that expressions such as ‘${prefix}/lib’ expand with only one slash between directory names. See the end of this section for details on when and how to use these variables.

Variable: bindir ¶

The directory for installing executables that users run.

Variable: datadir ¶

The directory for installing idiosyncratic read-only architecture-independent data.

Variable: datarootdir ¶

The root of the directory tree for read-only architecture-independent data files.

Variable: docdir ¶

The directory for installing documentation files (other than Info and man).

Variable: dvidir ¶

The directory for installing documentation files in DVI format.

Variable: exec_prefix ¶

The installation prefix for architecture-dependent files. By default it’s the same as prefix. You should avoid installing anything directly to exec_prefix. However, the default value for directories containing architecture-dependent files should be relative to exec_prefix.

Variable: htmldir ¶

The directory for installing HTML documentation.

Variable: includedir ¶

The directory for installing C header files.

Variable: infodir ¶

The directory for installing documentation in Info format.

Variable: libdir ¶

The directory for installing object code libraries.

Variable: libexecdir ¶

The directory for installing executables that other programs run.

Variable: localedir ¶

The directory for installing locale-dependent but architecture-independent data, such as message catalogs. This directory usually has a subdirectory per locale.

Variable: localstatedir ¶

The directory for installing modifiable single-machine data. Content in this directory typically survives a reboot.

Variable: runstatedir ¶

The directory for installing temporary modifiable single-machine data. Content in this directory survives as long as the process is running (such as pid files), as contrasted with /tmp that may be periodically cleaned. Conversely, this directory is typically cleaned on a reboot. By default, this is a subdirectory of localstatedir.

Variable: mandir ¶

The top-level directory for installing documentation in man format.

Variable: oldincludedir ¶

The directory for installing C header files for non-GCC compilers.

Variable: pdfdir ¶

The directory for installing PDF documentation.

Variable: prefix ¶

The common installation prefix for all files. If exec_prefix is defined to a different value, prefix is used only for architecture-independent files.

Variable: psdir ¶

The directory for installing PostScript documentation.

Variable: sbindir ¶

The directory for installing executables that system administrators run.

Variable: sharedstatedir ¶

The directory for installing modifiable architecture-independent data.

Variable: sysconfdir ¶

The directory for installing read-only single-machine data.

Most of these variables have values that rely on prefix or exec_prefix. It is deliberate that the directory output variables keep them unexpanded: typically ‘@datarootdir@’ is replaced by ‘${prefix}/share’, not ‘/usr/local/share’, and ‘@datadir@’ is replaced by ‘${datarootdir}’.

This behavior is mandated by the GNU Coding Standards, so that when the user runs:

‘make’

she can still specify a different prefix from the one specified to configure, in which case, if needed, the package should hard code dependencies corresponding to the make-specified prefix.

‘make install’

she can specify a different installation location, in which case the package must still depend on the location which was compiled in (i.e., never recompile when ‘make install’ is run). This is an extremely important feature, as many people may decide to install all the files of a package grouped together, and then install links from the final locations to there.

In order to support these features, it is essential that datarootdir remains defined as ‘${prefix}/share’, so that its value can be expanded based on the current value of prefix.

A corollary is that you should not use these variables except in makefiles. For instance, instead of trying to evaluate datadir in configure and hard-coding it in makefiles using e.g., ‘AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])’, you should add -DDATADIR='$(datadir)' to your makefile’s definition of CPPFLAGS (AM_CPPFLAGS if you are also using Automake).

Similarly, you should not rely on AC_CONFIG_FILES to replace bindir and friends in your shell scripts and other files; instead, let make manage their replacement. For instance Autoconf ships templates of its shell scripts ending with ‘.in’, and uses a makefile snippet similar to the following to build scripts like autoheader and autom4te:

edit = sed \
        -e 's|@bindir[@]|$(bindir)|g' \
        -e 's|@pkgdatadir[@]|$(pkgdatadir)|g' \
        -e 's|@prefix[@]|$(prefix)|g'

autoheader autom4te: Makefile
        rm -f $@ $@.tmp
        srcdir=''; \
          test -f ./$@.in || srcdir=$(srcdir)/; \
          $(edit) $${srcdir}$@.in >$@.tmp
        chmod +x $@.tmp
        chmod a-w $@.tmp
        mv $@.tmp $@

autoheader: $(srcdir)/autoheader.in
autom4te: $(srcdir)/autom4te.in

Some details are noteworthy:

‘@bindir[@]’

The brackets prevent configure from replacing ‘@bindir@’ in the Sed expression itself. Brackets are preferable to a backslash here, since Posix says ‘\@’ is not portable.

‘$(bindir)’

Don’t use ‘@bindir@’! Use the matching makefile variable instead.

‘$(pkgdatadir)’

The example takes advantage of the variable ‘$(pkgdatadir)’ provided by Automake; it is equivalent to ‘$(datadir)/$(PACKAGE)’.

‘/’

Don’t use ‘/’ in the Sed expressions that replace file names since most likely the variables you use, such as ‘$(bindir)’, contain ‘/’. Use a shell metacharacter instead, such as ‘|’.

special characters

File names, file name components, and the value of VPATH should not contain shell metacharacters or white space. See Special Characters in Output Variables.

dependency on Makefile

Since edit uses values that depend on the configuration specific values (prefix, etc.) and not only on VERSION and so forth, the output depends on Makefile, not configure.ac.

‘$@’

The main rule is generic, and uses ‘$@’ extensively to avoid the need for multiple copies of the rule.

Separated dependencies and single suffix rules

You can’t use them! The above snippet cannot be (portably) rewritten as:

autoconf autoheader: Makefile

.in:
        rm -f $@ $@.tmp
        $(edit) $< >$@.tmp
        chmod +x $@.tmp
        mv $@.tmp $@

See Single Suffix Rules and Separated Dependencies, for details.

‘$(srcdir)’

Be sure to specify the name of the source directory, otherwise the package won’t support separated builds.

For the more specific installation of Erlang libraries, the following variables are defined:

Variable: ERLANG_INSTALL_LIB_DIR ¶

The common parent directory of Erlang library installation directories. This variable is set by calling the AC_ERLANG_SUBST_INSTALL_LIB_DIR macro in configure.ac.

Variable: ERLANG_INSTALL_LIB_DIR_library ¶

The installation directory for Erlang library library. This variable is set by using the ‘AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR’ macro in configure.ac.

See Erlang Libraries, for details.

4.8.3 Changed Directory Variables

In Autoconf 2.60, the set of directory variables has changed, and the defaults of some variables have been adjusted (see Installation Directory Variables) to changes in the GNU Coding Standards. Notably, datadir, infodir, and mandir are now expressed in terms of datarootdir. If you are upgrading from an earlier Autoconf version, you may need to adjust your files to ensure that the directory variables are substituted correctly (see How Do I #define Installation Directories?), and that a definition of datarootdir is in place. For example, in a Makefile.in, adding

datarootdir = @datarootdir@

is usually sufficient. If you use Automake to create Makefile.in, it will add this for you.

To help with the transition, Autoconf warns about files that seem to use datarootdir without defining it. In some cases, it then expands the value of $datarootdir in substitutions of the directory variables. The following example shows such a warning:

$ cat configure.ac
AC_INIT
AC_CONFIG_FILES([Makefile])
AC_OUTPUT
$ cat Makefile.in
prefix = @prefix@
datadir = @datadir@
$ autoconf
$ configure
configure: creating ./config.status
config.status: creating Makefile
config.status: WARNING:
               Makefile.in seems to ignore the --datarootdir setting
$ cat Makefile
prefix = /usr/local
datadir = ${prefix}/share

Usually one can easily change the file to accommodate both older and newer Autoconf releases:

$ cat Makefile.in
prefix = @prefix@
datarootdir = @datarootdir@
datadir = @datadir@
$ configure
configure: creating ./config.status
config.status: creating Makefile
$ cat Makefile
prefix = /usr/local
datarootdir = ${prefix}/share
datadir = ${datarootdir}

In some cases, however, the checks may not be able to detect that a suitable initialization of datarootdir is in place, or they may fail to detect that such an initialization is necessary in the output file. If, after auditing your package, there are still spurious configure warnings about datarootdir, you may add the line

AC_DEFUN([AC_DATAROOTDIR_CHECKED])

to your configure.ac to disable the warnings. This is an exception to the usual rule that you should not define a macro whose name begins with AC_ (see Macro Names).

4.8.4 Build Directories

You can support compiling a software package for several architectures simultaneously from the same copy of the source code. The object files for each architecture are kept in their own directory.

To support doing this, make uses the VPATH variable to find the files that are in the source directory. GNU Make can do this. Most other recent make programs can do this as well, though they may have difficulties and it is often simpler to recommend GNU make (see VPATH and Make). Older make programs do not support VPATH; when using them, the source code must be in the same directory as the object files.

If you are using GNU Automake, the remaining details in this section are already covered for you, based on the contents of your Makefile.am. But if you are using Autoconf in isolation, then supporting VPATH requires the following in your Makefile.in:

srcdir = @srcdir@
VPATH = @srcdir@

Do not set VPATH to the value of another variable (see Variables listed in VPATH.

configure substitutes the correct value for srcdir when it produces Makefile.

Do not use the make variable $<, which expands to the file name of the file in the source directory (found with VPATH), except in implicit rules. (An implicit rule is one such as ‘.c.o’, which tells how to create a .o file from a .c file.) Some versions of make do not set $< in explicit rules; they expand it to an empty value.

Instead, Make command lines should always refer to source files by prefixing them with ‘$(srcdir)/’. It’s safer to quote the source directory name, in case it contains characters that are special to the shell. Because ‘$(srcdir)’ is expanded by Make, single-quoting works and is safer than double-quoting. For example:

time.info: time.texinfo
        $(MAKEINFO) '$(srcdir)/time.texinfo'

4.8.5 Automatic Remaking

You can put rules like the following in the top-level Makefile.in for a package to automatically update the configuration information when you change the configuration files. This example includes all of the optional files, such as aclocal.m4 and those related to configuration header files. Omit from the Makefile.in rules for any of these files that your package does not use.

The ‘$(srcdir)/’ prefix is included because of limitations in the VPATH mechanism.

The stamp- files are necessary because the timestamps of config.h.in and config.h are not changed if remaking them does not change their contents. This feature avoids unnecessary recompilation. You should include the file stamp-h.in in your package’s distribution, so that make considers config.h.in up to date. Don’t use touch (see Limitations of Usual Tools); instead, use echo (using date would cause needless differences, hence CVS conflicts, etc.).

$(srcdir)/configure: configure.ac aclocal.m4
        cd '$(srcdir)' && autoconf

# autoheader might not change config.h.in, so touch a stamp file.
$(srcdir)/config.h.in: stamp-h.in ;
$(srcdir)/stamp-h.in: configure.ac aclocal.m4
        cd '$(srcdir)' && autoheader
        echo timestamp > '$(srcdir)/stamp-h.in'

config.h: stamp-h ;
stamp-h: config.h.in config.status
        ./config.status

Makefile: Makefile.in config.status
        ./config.status

config.status: configure
        ./config.status --recheck

(Be careful if you copy these lines directly into your makefile, as you need to convert the indented lines to start with the tab character.)

In addition, you should use

AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])

so config.status ensures that config.h is considered up to date. See Outputting Files, for more information about AC_OUTPUT.

See config.status Invocation, for more examples of handling configuration-related dependencies.

4.9.1 Configuration Header Templates

Your distribution should contain a template file that looks as you want the final header file to look, including comments, with #undef statements which are used as hooks. For example, suppose your configure.ac makes these calls:

AC_CONFIG_HEADERS([conf.h])
AC_CHECK_HEADERS([unistd.h])

Then you could have code like the following in conf.h.in. The conf.h created by configure defines ‘HAVE_UNISTD_H’ to 1, if and only if the system has unistd.h.

/* Define as 1 if you have unistd.h.  */
#undef HAVE_UNISTD_H

The format of the template file is stricter than what the C preprocessor is required to accept. A directive line should contain only whitespace, ‘#undef’, and ‘HAVE_UNISTD_H’. The use of ‘#define’ instead of ‘#undef’, or of comments on the same line as ‘#undef’, is strongly discouraged. Each hook should only be listed once. Other preprocessor lines, such as ‘#ifdef’ or ‘#include’, are copied verbatim from the template into the generated header.

Since it is a tedious task to keep a template header up to date, you may use autoheader to generate it, see Using autoheader to Create config.h.in.

During the instantiation of the header, each ‘#undef’ line in the template file for each symbol defined by ‘AC_DEFINE’ is changed to an appropriate ‘#define’. If the corresponding ‘AC_DEFINE’ has not been executed during the configure run, the ‘#undef’ line is commented out. (This is important, e.g., for ‘_POSIX_SOURCE’: on many systems, it can be implicitly defined by the compiler, and undefining it in the header would then break compilation of subsequent headers.)

Currently, all remaining ‘#undef’ lines in the header template are commented out, whether or not there was a corresponding ‘AC_DEFINE’ for the macro name; but this behavior is not guaranteed for future releases of Autoconf.

Generally speaking, since you should not use ‘#define’, and you cannot guarantee whether a ‘#undef’ directive in the header template will be converted to a ‘#define’ or commented out in the generated header file, the template file cannot be used for conditional definition effects. Consequently, if you need to use the construct

#ifdef THIS
# define THAT
#endif

you must place it outside of the template. If you absolutely need to hook it to the config header itself, please put the directives to a separate file, and ‘#include’ that file from the config header template. If you are using autoheader, you would probably use ‘AH_BOTTOM’ to append the ‘#include’ directive.

4.9.2 Using autoheader to Create config.h.in

The autoheader program can create a template file of C ‘#define’ statements for configure to use. It searches for the first invocation of AC_CONFIG_HEADERS in configure sources to determine the name of the template. (If the first call of AC_CONFIG_HEADERS specifies more than one input file name, autoheader uses the first one.)

It is recommended that only one input file is used. If you want to append a boilerplate code, it is preferable to use ‘AH_BOTTOM([#include <conf_post.h>])’. File conf_post.h is not processed during the configuration then, which make things clearer. Analogically, AH_TOP can be used to prepend a boilerplate code.

In order to do its job, autoheader needs you to document all of the symbols that you might use. Typically this is done via an AC_DEFINE or AC_DEFINE_UNQUOTED call whose first argument is a literal symbol and whose third argument describes the symbol (see Defining C Preprocessor Symbols). Alternatively, you can use AH_TEMPLATE (see Autoheader Macros), or you can supply a suitable input file for a subsequent configuration header file. Symbols defined by Autoconf’s builtin tests are already documented properly; you need to document only those that you define yourself.

You might wonder why autoheader is needed: after all, why would configure need to “patch” a config.h.in to produce a config.h instead of just creating config.h from scratch? Well, when everything rocks, the answer is just that we are wasting our time maintaining autoheader: generating config.h directly is all that is needed. When things go wrong, however, you’ll be thankful for the existence of autoheader.

The fact that the symbols are documented is important in order to check that config.h makes sense. The fact that there is a well-defined list of symbols that should be defined (or not) is also important for people who are porting packages to environments where configure cannot be run: they just have to fill in the blanks.

But let’s come back to the point: the invocation of autoheader…

If you give autoheader an argument, it uses that file instead of configure.ac and writes the header file to the standard output instead of to config.h.in. If you give autoheader an argument of -, it reads the standard input instead of configure.ac and writes the header file to the standard output.

autoheader accepts the following options:

--help

-h

Print a summary of the command line options and exit.

--version

-V

Print the version number of Autoconf and exit.

--verbose

-v

Report processing steps.

--debug

-d

Don’t remove the temporary files.

--force

-f

Remake the template file even if newer than its input files.

--include=dir

-I dir

Append dir to the include path. Multiple invocations accumulate.

--prepend-include=dir

-B dir

Prepend dir to the include path. Multiple invocations accumulate.

--warnings=category[,category...] ¶

-Wcategory[,category...]

Enable or disable warnings related to each category. See m4_warn, for a comprehensive list of categories. Special values include:

‘all’

Enable all categories of warnings.

‘none’

Disable all categories of warnings.

‘error’

Treat all warnings as errors.

‘no-category’

Disable warnings falling into category.

The environment variable WARNINGS may also be set to a comma-separated list of warning categories to enable or disable. It is interpreted exactly the same way as the argument of --warnings, but unknown categories are silently ignored. The command line takes precedence; for instance, if WARNINGS is set to obsolete, but -Wnone is given on the command line, no warnings will be issued.

Some categories of warnings are on by default. Again, for details see m4_warn.

4.9.3 Autoheader Macros

autoheader scans configure.ac and figures out which C preprocessor symbols it might define. It knows how to generate templates for symbols defined by AC_CHECK_HEADERS, AC_CHECK_FUNCS etc., but if you AC_DEFINE any additional symbol, you must define a template for it. If there are missing templates, autoheader fails with an error message.

The template for a symbol is created by autoheader from the description argument to an AC_DEFINE; see Defining C Preprocessor Symbols.

For special needs, you can use the following macros.

Macro: AH_TEMPLATE (key, description) ¶

Tell autoheader to generate a template for key. This macro generates standard templates just like AC_DEFINE when a description is given.

For example:

AH_TEMPLATE([NULL_DEVICE],
  [Name of the file to open to get
   a null file, or a data sink.])

generates the following template, with the description properly justified.

/* Name of the file to open to get a null file, or a data sink. */
#undef NULL_DEVICE

Macro: AH_VERBATIM (key, template) ¶

Tell autoheader to include the template as-is in the header template file. This template is associated with the key, which is used to sort all the different templates and guarantee their uniqueness. It should be a symbol that can be defined via AC_DEFINE.

Macro: AH_TOP (text) ¶

Include text at the top of the header template file.

Macro: AH_BOTTOM (text) ¶

Include text at the bottom of the header template file.

Please note that text gets included “verbatim” to the template file, not to the resulting config header, so it can easily get mangled when the template is processed. There is rarely a need for something other than

AH_BOTTOM([#include <custom.h>])

5.1.1 Standard Symbols

All the generic macros that AC_DEFINE a symbol as a result of their test transform their argument values to a standard alphabet. First, argument is converted to upper case and any asterisks (‘*’) are each converted to ‘P’. Any remaining characters that are not alphanumeric are converted to underscores.

For instance,

AC_CHECK_TYPES([struct $Expensive*])

defines the symbol ‘HAVE_STRUCT__EXPENSIVEP’ if the check succeeds.

5.1.2 Default Includes

Test programs frequently need to include headers that may or may not be available on the system whose features are being tested. Each test can use all the preprocessor macros that have been AC_DEFINEd by previous tests, so for example one may write

#include <time.h>
#ifdef HAVE_SYS_TIME_H
# include <sys/time.h>
#endif

if sys/time.h has already been tested for.

All hosted environments that are still of interest for portable code provide all of the headers specified in C89 (as amended in 1995): assert.h, ctype.h, errno.h, float.h, iso646.h, limits.h, locale.h, math.h, setjmp.h, signal.h, stdarg.h, stddef.h, stdio.h, stdlib.h, string.h, time.h, wchar.h, and wctype.h. Most programs can safely include these headers unconditionally. A program not intended to be portable to C89 can also safely include the C99-specified header stdbool.h. Other headers, including headers from C99 and later revisions of the C standard, might need to be tested for (see Header Files) or their bugs may need to be worked around (see Gnulib).

If your program needs to be portable to a freestanding environment, such as an embedded OS that doesn’t provide all of the facilities of the C89 standard library, you may need to test for some of the above headers as well. Note that many Autoconf macros internally assume that the complete set of C89 headers are available.

Most generic macros use the following macro to provide a default set of includes:

Macro: AC_INCLUDES_DEFAULT ([include-directives]) ¶

Expand to include-directives if present and nonempty, otherwise to:

#include <stddef.h>
#ifdef HAVE_STDIO_H
# include <stdio.h>
#endif
#ifdef HAVE_STDLIB_H
# include <stdlib.h>
#endif
#ifdef HAVE_STRING_H
# include <string.h>
#endif
#ifdef HAVE_INTTYPES_H
# include <inttypes.h>
#endif
#ifdef HAVE_STDINT_H
# include <stdint.h>
#endif
#ifdef HAVE_STRINGS_H
# include <strings.h>
#endif
#ifdef HAVE_SYS_TYPES_H
# include <sys/types.h>
#endif
#ifdef HAVE_SYS_STAT_H
# include <sys/stat.h>
#endif
#ifdef HAVE_UNISTD_H
# include <unistd.h>
#endif

Using this macro without include-directives has the side effect of checking for stdio.h, stdlib.h, string.h, inttypes.h, stdint.h, strings.h, sys/types.h, sys/stat.h, and unistd.h, as if by AC_CHECK_HEADERS_ONCE. For backward compatibility, the macro STDC_HEADERS will be defined when both stdlib.h and string.h are available.

Portability Note: It is safe for most programs to assume the presence of all of the headers required by the original 1990 C standard. AC_INCLUDES_DEFAULT checks for stdio.h, stdlib.h, and string.h, even though they are in that list, because they might not be available when compiling for a “freestanding environment” (in which most of the features of the C library are optional). You probably do not need to write ‘#ifdef HAVE_STDIO_H’ in your own code.

inttypes.h and stdint.h were added to C in the 1999 revision of the standard, and strings.h, sys/types.h, sys/stat.h, and unistd.h are POSIX extensions. You should guard uses of these headers with appropriate conditionals.

Macro: AC_CHECK_INCLUDES_DEFAULT ¶

Check for all the headers that AC_INCLUDES_DEFAULT would check for as a side-effect, if this has not already happened.

This macro mainly exists so that autoupdate can replace certain obsolete constructs with it. You should not need to use it yourself; in fact, it is likely to be safe to delete it from any script in which it appears. (autoupdate does not know whether preprocessor macros such as HAVE_STDINT_H are used in the program, nor whether they would get defined as a side-effect of other checks.)

5.2.1 Particular Program Checks

These macros check for particular programs—whether they exist, and in some cases whether they support certain features.

Macro: AC_PROG_AR ¶

Set output variable AR to ‘ar’ if ar is found, and otherwise to ‘:’ (do nothing).

Macro: AC_PROG_AWK ¶

Check for gawk, mawk, nawk, and awk, in that order, and set output variable AWK to the first one that is found. It tries gawk first because that is reported to be the best implementation. The result can be overridden by setting the variable AWK or the cache variable ac_cv_prog_AWK.

Using this macro is sufficient to avoid the pitfalls of traditional awk (see Limitations of Usual Tools).

Macro: AC_PROG_GREP ¶

Look for the best available grep or ggrep that accepts the longest input lines possible, and that supports multiple -e options. Set the output variable GREP to whatever is chosen. See Limitations of Usual Tools, for more information about portability problems with the grep command family. The result can be overridden by setting the GREP variable and is cached in the ac_cv_path_GREP variable.

Macro: AC_PROG_EGREP ¶

Check whether $GREP -E works, or else look for the best available egrep or gegrep that accepts the longest input lines possible. Set the output variable EGREP to whatever is chosen. The result can be overridden by setting the EGREP variable and is cached in the ac_cv_path_EGREP variable.

Macro: AC_PROG_FGREP ¶

Check whether $GREP -F works, or else look for the best available fgrep or gfgrep that accepts the longest input lines possible. Set the output variable FGREP to whatever is chosen. The result can be overridden by setting the FGREP variable and is cached in the ac_cv_path_FGREP variable.

Macro: AC_PROG_INSTALL ¶

Set output variable INSTALL to the name of a BSD-compatible install program, if one is found in the current PATH. Otherwise, set INSTALL to ‘dir/install-sh -c’, checking the directories specified to AC_CONFIG_AUX_DIR (or its default directories) to determine dir (see Outputting Files). Also set the variables INSTALL_PROGRAM and INSTALL_SCRIPT to ‘${INSTALL}’ and INSTALL_DATA to ‘${INSTALL} -m 644’.

‘@INSTALL@’ is special, as its value may vary for different configuration files.

This macro screens out various instances of install known not to work. It prefers to find a C program rather than a shell script, for speed. Instead of install-sh, it can also use install.sh, but that name is obsolete because some make programs have a rule that creates install from it if there is no makefile. Further, this macro requires install to be able to install multiple files into a target directory in a single invocation.

Autoconf comes with a copy of install-sh that you can use. If you use AC_PROG_INSTALL, you must include install-sh in your distribution; otherwise autoreconf and configure will produce an error message saying they can’t find it—even if the system you’re on has a good install program. This check is a safety measure to prevent you from accidentally leaving that file out, which would prevent your package from installing on systems that don’t have a BSD-compatible install program.

If you need to use your own installation program because it has features not found in standard install programs, there is no reason to use AC_PROG_INSTALL; just put the file name of your program into your Makefile.in files.

The result of the test can be overridden by setting the variable INSTALL or the cache variable ac_cv_path_install.

Macro: AC_PROG_MKDIR_P ¶

Set output variable MKDIR_P to a program that ensures that for each argument, a directory named by this argument exists, creating it and its parent directories if needed, and without race conditions when two instances of the program attempt to make the same directory at nearly the same time.

This macro uses the equivalent of the ‘mkdir -p’ command. Ancient versions of mkdir are vulnerable to race conditions, so if you want to support parallel installs from different packages into the same directory you should use a non-ancient mkdir.

This macro is related to the AS_MKDIR_P macro (see Programming in M4sh), but it sets an output variable intended for use in other files, whereas AS_MKDIR_P is intended for use in scripts like configure. Also, AS_MKDIR_P does not accept options, but MKDIR_P supports the -m option, e.g., a makefile might invoke $(MKDIR_P) -m 0 dir to create an inaccessible directory, and conversely a makefile should use $(MKDIR_P) -- $(FOO) if FOO might yield a value that begins with ‘-’.

The result of the test can be overridden by setting the variable MKDIR_P or the cache variable ac_cv_path_mkdir.

Macro: AC_PROG_LEX (options) ¶

Search for a lexical analyzer generator, preferring flex to plain lex. Output variable LEX is set to whichever program is available. If neither program is available, LEX is set to ‘:’; for packages that ship the generated file.yy.c alongside the source file.l, this default allows users without a lexer generator to still build the package even if the timestamp for file.l is inadvertently changed.

The name of the program to use can be overridden by setting the output variable LEX or the cache variable ac_cv_prog_LEX when running configure.

If a lexical analyzer generator is found, this macro performs additional checks for common portability pitfalls. If these additional checks fail, LEX is reset to ‘:’; otherwise the following additional macros and variables are provided.

Preprocessor macro YYTEXT_POINTER is defined if the lexer skeleton, by default, declares yytext as a ‘char *’ rather than a ‘char []’.

Output variable LEX_OUTPUT_ROOT is set to the base of the file name that the lexer generates; this is usually either lex.yy or lexyy.

If generated lexers need a library to work, output variable LEXLIB is set to a link option for that library (e.g., -ll), otherwise it is set to empty.

The options argument modifies the behavior of AC_PROG_LEX. It should be a whitespace-separated list of options. Currently there are only two options, and they are mutually exclusive:

yywrap

Indicate that the library in LEXLIB needs to define the function yywrap. If a library that defines this function cannot be found, LEX will be reset to ‘:’.

noyywrap

Indicate that the library in LEXLIB does not need to define the function yywrap. configure will not search for it at all.

Prior to Autoconf 2.70, AC_PROG_LEX did not take any arguments, and its behavior was different from either of the above possibilities: it would search for a library that defines yywrap, and would set LEXLIB to that library if it finds one. However, if a library that defines this function could not be found, LEXLIB would be left empty and LEX would not be reset. This behavior was due to a bug, but several packages came to depend on it, so AC_PROG_LEX still does this if neither the yywrap nor the noyywrap option is given.

Usage of AC_PROG_LEX without choosing one of the yywrap or noyywrap options is deprecated. It is usually better to use noyywrap and define the yywrap function yourself, as this almost always renders the LEXLIB unnecessary.

Caution: As a side-effect of the test, this macro may delete any file in the configure script’s current working directory named lex.yy.c or lexyy.c.

Caution: Packages that ship a generated lex.yy.c cannot assume that the definition of YYTEXT_POINTER matches the code in that file. They also cannot assume that LEXLIB provides the library routines required by the code in that file.

If you use Flex to generate lex.yy.c, you can work around these limitations by defining yywrap and main yourself (rendering -lfl unnecessary), and by using either the --array or --pointer options to control how yytext is declared. The code generated by Flex is also more portable than the code generated by historical versions of Lex.

If you have used Flex to generate lex.yy.c, and especially if your scanner depends on Flex features, we recommend you use this Autoconf snippet to prevent the scanner being regenerated with historical Lex:

AC_PROG_LEX
AS_IF([test "x$LEX" != xflex],
  [LEX="$SHELL $missing_dir/missing flex"
   AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
   AC_SUBST([LEXLIB], [''])])

The shell script missing can be found in the Automake distribution.

Remember that the user may have supplied an alternate location in LEX, so if Flex is required, it is better to check that the user provided something sufficient by parsing the output of ‘$LEX --version’ than by simply relying on test "x$LEX" = xflex.

Macro: AC_PROG_LN_S ¶

If ‘ln -s’ works on the current file system (the operating system and file system support symbolic links), set the output variable LN_S to ‘ln -s’; otherwise, if ‘ln’ works, set LN_S to ‘ln’, and otherwise set it to ‘cp -pR’.

If you make a link in a directory other than the current directory, its meaning depends on whether ‘ln’ or ‘ln -s’ is used. To safely create links using ‘$(LN_S)’, either find out which form is used and adjust the arguments, or always invoke ln in the directory where the link is to be created.

In other words, it does not work to do:

$(LN_S) foo /x/bar

Instead, do:

(cd /x && $(LN_S) foo bar)

Macro: AC_PROG_RANLIB ¶

Set output variable RANLIB to ‘ranlib’ if ranlib is found, and otherwise to ‘:’ (do nothing).

Macro: AC_PROG_SED ¶

Set output variable SED to a Sed implementation that conforms to Posix and does not have arbitrary length limits. Report an error if no acceptable Sed is found. See Limitations of Usual Tools, for more information about portability problems with Sed.

The result of this test can be overridden by setting the SED variable and is cached in the ac_cv_path_SED variable.

Macro: AC_PROG_YACC ¶

If bison is found, set output variable YACC to ‘bison -y’. Otherwise, if byacc is found, set YACC to ‘byacc’. Otherwise set YACC to ‘yacc’. The result of this test can be influenced by setting the variable YACC or the cache variable ac_cv_prog_YACC.

5.2.2 Generic Program and File Checks

These macros are used to find programs not covered by the “particular” test macros. If you need to check the behavior of a program as well as find out whether it is present, you have to write your own test for it (see Writing Tests). By default, these macros use the environment variable PATH. If you need to check for a program that might not be in the user’s PATH, you can pass a modified path to use instead, like this:

AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
             [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl
[/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc])

You are strongly encouraged to declare the variable passed to AC_CHECK_PROG etc. as precious. See Setting Output Variables, AC_ARG_VAR, for more details.

Macro: AC_CHECK_PROG (variable, prog-to-check-for, value-if-found, [value-if-not-found], [path = ‘$PATH’], [reject]) ¶

Check whether program prog-to-check-for exists in path. If it is found, set variable to value-if-found, otherwise to value-if-not-found, if given. Always pass over reject (an absolute file name) even if it is the first found in the search path; in that case, set variable using the absolute file name of the prog-to-check-for found that is not reject. If variable was already set, do nothing. Calls AC_SUBST for variable. The result of this test can be overridden by setting the variable variable or the cache variable ac_cv_prog_variable.

Macro: AC_CHECK_PROGS (variable, progs-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Check for each program in the blank-separated list progs-to-check-for existing in the path. If one is found, set variable to the name of that program. Otherwise, continue checking the next program in the list. If none of the programs in the list are found, set variable to value-if-not-found; if value-if-not-found is not specified, the value of variable is not changed. Calls AC_SUBST for variable. The result of this test can be overridden by setting the variable variable or the cache variable ac_cv_prog_variable.

Macro: AC_CHECK_TARGET_TOOL (variable, prog-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_PROG, but first looks for prog-to-check-for with a prefix of the target type as determined by AC_CANONICAL_TARGET, followed by a dash (see Getting the Canonical System Type). If the tool cannot be found with a prefix, and if the build and target types are equal, then it is also searched for without a prefix.

As noted in Specifying target triplets, the target is rarely specified, because most of the time it is the same as the host: it is the type of system for which any compiler tool in the package produces code. What this macro looks for is, for example, a tool (assembler, linker, etc.) that the compiler driver (gcc for the GNU C Compiler) uses to produce objects, archives or executables.

Macro: AC_CHECK_TOOL (variable, prog-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_PROG, but first looks for prog-to-check-for with a prefix of the host type as specified by --host, followed by a dash. For example, if the user runs ‘configure --build=x86_64-gnu --host=aarch64-linux-gnu’, then this call:

AC_CHECK_TOOL([RANLIB], [ranlib], [:])

sets RANLIB to aarch64-linux-gnu-ranlib if that program exists in path, or otherwise to ‘ranlib’ if that program exists in path, or to ‘:’ if neither program exists.

When cross-compiling, this macro will issue a warning if no program prefixed with the host type could be found. For more information, see Specifying target triplets.

Macro: AC_CHECK_TARGET_TOOLS (variable, progs-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_TARGET_TOOL, each of the tools in the list progs-to-check-for are checked with a prefix of the target type as determined by AC_CANONICAL_TARGET, followed by a dash (see Getting the Canonical System Type). If none of the tools can be found with a prefix, and if the build and target types are equal, then the first one without a prefix is used. If a tool is found, set variable to the name of that program. If none of the tools in the list are found, set variable to value-if-not-found; if value-if-not-found is not specified, the value of variable is not changed. Calls AC_SUBST for variable.

Macro: AC_CHECK_TOOLS (variable, progs-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_TOOL, each of the tools in the list progs-to-check-for are checked with a prefix of the host type as determined by AC_CANONICAL_HOST, followed by a dash (see Getting the Canonical System Type). If none of the tools can be found with a prefix, then the first one without a prefix is used. If a tool is found, set variable to the name of that program. If none of the tools in the list are found, set variable to value-if-not-found; if value-if-not-found is not specified, the value of variable is not changed. Calls AC_SUBST for variable.

When cross-compiling, this macro will issue a warning if no program prefixed with the host type could be found. For more information, see Specifying target triplets.

Macro: AC_PATH_PROG (variable, prog-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_PROG, but set variable to the absolute name of prog-to-check-for if found. The result of this test can be overridden by setting the variable variable. A positive result of this test is cached in the ac_cv_path_variable variable.

Macro: AC_PATH_PROGS (variable, progs-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_PROGS, but if any of progs-to-check-for are found, set variable to the absolute name of the program found. The result of this test can be overridden by setting the variable variable. A positive result of this test is cached in the ac_cv_path_variable variable.

Macro: AC_PATH_PROGS_FEATURE_CHECK (variable, progs-to-check-for, feature-test, [action-if-not-found], [path = ‘$PATH’]) ¶

This macro was introduced in Autoconf 2.62. If variable is not empty, then set the cache variable ac_cv_path_variable to its value. Otherwise, check for each program in the blank-separated list progs-to-check-for existing in path. For each program found, execute feature-test with ac_path_variable set to the absolute name of the candidate program. If no invocation of feature-test sets the shell variable ac_cv_path_variable, then action-if-not-found is executed. feature-test will be run even when ac_cv_path_variable is set, to provide the ability to choose a better candidate found later in path; to accept the current setting and bypass all further checks, feature-test can execute ac_path_variable_found=:.

Note that this macro has some subtle differences from AC_CHECK_PROGS. It is designed to be run inside AC_CACHE_VAL, therefore, it should have no side effects. In particular, variable is not set to the final value of ac_cv_path_variable, nor is AC_SUBST automatically run. Also, on failure, any action can be performed, whereas AC_CHECK_PROGS only performs variable=value-if-not-found.

Here is an example, similar to what Autoconf uses in its own configure script. It will search for an implementation of m4 that supports the indir builtin, even if it goes by the name gm4 or is not the first implementation on PATH.

AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4],
  [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4],
    [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4`
      test "x$m4out" = x0 \
      && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]],
    [AC_MSG_ERROR([could not find m4 that supports indir])])])
AC_SUBST([M4], [$ac_cv_path_M4])

Macro: AC_PATH_TARGET_TOOL (variable, prog-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_TARGET_TOOL, but set variable to the absolute name of the program if it is found.

Macro: AC_PATH_TOOL (variable, prog-to-check-for, [value-if-not-found], [path = ‘$PATH’]) ¶

Like AC_CHECK_TOOL, but set variable to the absolute name of the program if it is found.

When cross-compiling, this macro will issue a warning if no program prefixed with the host type could be found. For more information, see Specifying target triplets.

5.5.1 Portability of C Functions

Most usual functions can either be missing, or be buggy, or be limited on some architectures. This section tries to make an inventory of these portability issues. By definition, this list always requires additions. A much more complete list is maintained by the Gnulib project (see Gnulib), covering Current Posix Functions in Gnulib, Legacy Functions in Gnulib, and Glibc Functions in Gnulib. Please help us keep the Gnulib list as complete as possible.

exit

On ancient hosts, exit returned int. This is because exit predates void, and there was a long tradition of it returning int.

On current hosts, the problem more likely is that exit is not declared, due to C++ problems of some sort or another. For this reason we suggest that test programs not invoke exit, but return from main instead.

isinf

isnan

In C99 and later, isinf and isnan are macros. On some systems just macros are available (e.g., HP-UX and Solaris 10), on some systems both macros and functions (e.g., glibc 2.3.2), and on some systems only functions (e.g., IRIX 6). In some cases these functions are declared in nonstandard headers like <sunmath.h> and defined in non-default libraries like -lm or -lsunmath.

In C99 and later, isinf and isnan macros work correctly with long double arguments, but pre-C99 systems that use functions typically assume double arguments. On such a system, isinf incorrectly returns true for a finite long double argument that is outside the range of double.

The best workaround for these issues is to use Gnulib modules isinf and isnan (see Gnulib). But a lighter weight solution involves code like the following.

#include <math.h>

#ifndef isnan
# define isnan(x) \
    (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
     : sizeof (x) == sizeof (double) ? isnan_d (x) \
     : isnan_f (x))
static int isnan_f  (float       x) { return x != x; }
static int isnan_d  (double      x) { return x != x; }
static int isnan_ld (long double x) { return x != x; }
#endif

#ifndef isinf
# define isinf(x) \
    (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
     : sizeof (x) == sizeof (double) ? isinf_d (x) \
     : isinf_f (x))
static int isinf_f  (float       x)
{ return !isnan (x) && isnan (x - x); }
static int isinf_d  (double      x)
{ return !isnan (x) && isnan (x - x); }
static int isinf_ld (long double x)
{ return !isnan (x) && isnan (x - x); }
#endif

Some optimizing compilers mishandle these definitions, but systems with that bug typically have many other floating point corner-case compliance problems anyway, so it’s probably not worth worrying about.

malloc

The C standard says a successful call malloc (0) is implementation dependent. It can return either NULL or a new non-null pointer. The latter is more common (e.g., the GNU C Library) but is by no means universal. AC_FUNC_MALLOC can be used to insist on non-NULL (see Particular Function Checks).

putenv

Posix prefers setenv to putenv; among other things, putenv is not required of all Posix implementations, but setenv is.

Posix specifies that putenv puts the given string directly in environ, but some systems make a copy of it instead (e.g., glibc 2.0, or BSD). And when a copy is made, unsetenv might not free it, causing a memory leak (e.g., FreeBSD 4).

On some systems putenv ("FOO") removes ‘FOO’ from the environment, but this is not standard usage and it dumps core on some systems (e.g., AIX).

On MinGW, a call putenv ("FOO=") removes ‘FOO’ from the environment, rather than inserting it with an empty value.

realloc

It is problematic to call realloc with a zero size. The C standard says realloc (NULL, 0) is equivalent to malloc (0), which means one cannot portably tell whether the call has succeeded if it returns a null pointer. If ptr is non-null, the C standard says realloc (ptr, 0) has undefined behavior.

The AC_FUNC_REALLOC macro avoids some of these portability issues, and the Gnulib module realloc-gnu avoids more of them. See Particular Function Checks.

signal handler

In most cases, it is more robust to use sigaction when it is available, rather than signal.

snprintf

In C99 and later, if the output array isn’t big enough and if no other errors occur, snprintf and vsnprintf truncate the output and return the number of bytes that ought to have been produced. Some ancient systems returned the truncated length (e.g., GNU C Library 2.0.x or IRIX 6.5), and some a negative value (e.g., earlier GNU C Library versions).

strerror_r

Posix specifies that strerror_r returns an int, but many systems (e.g., GNU C Library version 2.36) provide a different version returning a char *. AC_FUNC_STRERROR_R can detect which is in use (see Particular Function Checks).

strnlen

AIX 4.3 provided a broken version which produces the following results:

strnlen ("foobar", 0) = 0
strnlen ("foobar", 1) = 3
strnlen ("foobar", 2) = 2
strnlen ("foobar", 3) = 1
strnlen ("foobar", 4) = 0
strnlen ("foobar", 5) = 6
strnlen ("foobar", 6) = 6
strnlen ("foobar", 7) = 6
strnlen ("foobar", 8) = 6
strnlen ("foobar", 9) = 6

sysconf

_SC_PAGESIZE is standard, but some older systems (e.g., HP-UX 9) have _SC_PAGE_SIZE instead. This can be tested with #ifdef.

unlink

The Posix spec says that unlink causes the given file to be removed only after there are no more open file handles for it. Some non-Posix hosts have trouble with this requirement, though, and some DOS variants even corrupt the file system.

unsetenv

On MinGW, unsetenv is not available, but a variable ‘FOO’ can be removed with a call putenv ("FOO="), as described under putenv above.

va_copy

C99 and later provide va_copy for copying va_list variables. It may be available in older environments too, though possibly as __va_copy (e.g., gcc in strict pre-C99 mode). These can be tested with #ifdef. A fallback to memcpy (&dst, &src, sizeof (va_list)) gives maximum portability.

va_list

va_list is not necessarily just a pointer. It can be a struct (e.g., gcc on Alpha), which means NULL is not portable. Or it can be an array (e.g., gcc in some PowerPC configurations), which means as a function parameter it can be effectively call-by-reference and library routines might modify the value back in the caller (e.g., vsnprintf in the GNU C Library 2.1).

Signed >>

Normally the C >> right shift of a signed type replicates the high bit, giving a so-called “arithmetic” shift. But care should be taken since Standard C doesn’t require that behavior. On a few platforms (e.g., Cray C by default) zero bits are shifted in, the same as a shift of an unsigned type.

Integer /

C divides signed integers by truncating their quotient toward zero, yielding the same result as Fortran. However, before C99 the standard allowed C implementations to take the floor or ceiling of the quotient in some cases. Hardly any implementations took advantage of this freedom, though, and it’s probably not worth worrying about this issue nowadays.

5.5.2 Particular Function Checks

These macros check for particular C functions—whether they exist, and in some cases how they respond when given certain arguments.

Macro: AC_FUNC_ALLOCA ¶

Check for the alloca function. Define HAVE_ALLOCA_H if alloca.h defines a working alloca. If not, look for a builtin alternative. If either method succeeds, define HAVE_ALLOCA. Otherwise, set the output variable ALLOCA to ‘${LIBOBJDIR}alloca.o’ and define C_ALLOCA (so programs can periodically call ‘alloca (0)’ to garbage collect). This variable is separate from LIBOBJS so multiple programs can share the value of ALLOCA without needing to create an actual library, in case only some of them use the code in LIBOBJS. The ‘${LIBOBJDIR}’ prefix serves the same purpose as in LIBOBJS (see AC_LIBOBJ vs. LIBOBJS).

Source files that use alloca should start with a piece of code like the following, to declare it properly.

#include <stdlib.h>
#include <stddef.h>
#ifdef HAVE_ALLOCA_H
# include <alloca.h>
#elif !defined alloca
# ifdef __GNUC__
#  define alloca __builtin_alloca
# elif defined _MSC_VER
#  include <malloc.h>
#  define alloca _alloca
# elif !defined HAVE_ALLOCA
#  ifdef  __cplusplus
extern "C"
#  endif
void *alloca (size_t);
# endif
#endif

If you don’t want to maintain this piece of code in your package manually, you can instead use the Gnulib module alloca-opt or alloca. See Gnulib.

Macro: AC_FUNC_CHOWN ¶

If the chown function is available and works (in particular, it should accept -1 for uid and gid), define HAVE_CHOWN. The result of this macro is cached in the ac_cv_func_chown_works variable.

If you want a workaround, that is, a chown function that is available and works, you can use the Gnulib module chown. See Gnulib.

Macro: AC_FUNC_CLOSEDIR_VOID ¶

If the closedir function does not return a meaningful value, define CLOSEDIR_VOID. Otherwise, callers ought to check its return value for an error indicator.

Currently this test is implemented by running a test program. When cross compiling the pessimistic assumption that closedir does not return a meaningful value is made.

The result of this macro is cached in the ac_cv_func_closedir_void variable.

This macro is obsolescent, as closedir returns a meaningful value on current systems. New programs need not use this macro.

Macro: AC_FUNC_ERROR_AT_LINE ¶

If the error_at_line function is not found, require an AC_LIBOBJ replacement of ‘error’.

The result of this macro is cached in the ac_cv_lib_error_at_line variable.

The AC_FUNC_ERROR_AT_LINE macro is obsolescent. New programs should use Gnulib’s error module. See Gnulib.

Macro: AC_FUNC_FNMATCH ¶

If the fnmatch function conforms to Posix, define HAVE_FNMATCH.

Unlike the other specific AC_FUNC macros, AC_FUNC_FNMATCH does not replace a broken/missing fnmatch. This is for historical reasons. See AC_REPLACE_FNMATCH below.

The result of this macro is cached in the ac_cv_func_fnmatch_works variable.

This macro is obsolescent. New programs should use Gnulib’s fnmatch-posix module. See Gnulib.

Macro: AC_FUNC_FNMATCH_GNU ¶

Behave like AC_REPLACE_FNMATCH (replace) but also test whether fnmatch supports GNU extensions. Detect common implementation bugs, for example, the bugs in the GNU C Library 2.1.

The result of this macro is cached in the ac_cv_func_fnmatch_gnu variable.

This macro is obsolescent. New programs should use Gnulib’s fnmatch-gnu module. See Gnulib.

Macro: AC_FUNC_FORK ¶

This macro checks for the fork and vfork functions. If a working fork is found, define HAVE_WORKING_FORK. This macro checks whether fork is just a stub by trying to run it.

If vfork.h is found, define HAVE_VFORK_H. If a working vfork is found, define HAVE_WORKING_VFORK. Otherwise, define vfork to be fork for backward compatibility with previous versions of autoconf. This macro checks for several known errors in implementations of vfork and considers the system to not have a working vfork if it detects any of them.

Since this macro defines vfork only for backward compatibility with previous versions of autoconf you’re encouraged to define it yourself in new code:

#ifndef HAVE_WORKING_VFORK
# define vfork fork
#endif

The results of this macro are cached in the ac_cv_func_fork_works and ac_cv_func_vfork_works variables. In order to override the test, you also need to set the ac_cv_func_fork and ac_cv_func_vfork variables.

Macro: AC_FUNC_FSEEKO ¶

If the fseeko and ftello functions are available, define HAVE_FSEEKO. Define _LARGEFILE_SOURCE if necessary to make the prototype visible.

Configure scripts that use AC_FUNC_FSEEKO should normally also use AC_SYS_LARGEFILE to ensure that off_t can represent all supported file sizes. See AC_SYS_LARGEFILE.

The Gnulib module fseeko invokes AC_FUNC_FSEEKO and also contains workarounds for other portability problems of fseeko. See Gnulib.

Macro: AC_FUNC_GETGROUPS ¶

Perform all the checks performed by AC_TYPE_GETGROUPS (see AC_TYPE_GETGROUPS). Then, if the getgroups function is available and known to work correctly, define HAVE_GETGROUPS. Set the output variable GETGROUPS_LIB to any libraries needed to get that function.

This macro relies on a list of systems with known, serious bugs in getgroups. If this list mis-identifies your system’s getgroups as buggy, or as not buggy, you can override it by setting the cache variable ac_cv_func_getgroups_works in a config.site file (see Setting Site Defaults). Please also report the error to the Autoconf Bugs mailing list.

The Gnulib module getgroups provides workarounds for additional, less severe portability problems with this function.

Macro: AC_FUNC_GETLOADAVG ¶

Check how to get the system load averages. To perform its tests properly, this macro needs the file getloadavg.c; therefore, be sure to set the AC_LIBOBJ replacement directory properly (see Generic Function Checks, AC_CONFIG_LIBOBJ_DIR).

If the system has the getloadavg function, define HAVE_GETLOADAVG, and set GETLOADAVG_LIBS to any libraries necessary to get that function. Also add GETLOADAVG_LIBS to LIBS. Otherwise, require an AC_LIBOBJ replacement for ‘getloadavg’ and possibly define several other C preprocessor macros and output variables:

1. Define C_GETLOADAVG.
2. Define SVR4, DGUX, UMAX, or UMAX4_3 if on those systems.
3. If nlist.h is found, define HAVE_NLIST_H.
4. If ‘struct nlist’ has an ‘n_un.n_name’ member, define HAVE_STRUCT_NLIST_N_UN_N_NAME. The obsolete symbol NLIST_NAME_UNION is still defined, but do not depend upon it.
5. Programs may need to be installed set-group-ID (or set-user-ID) for getloadavg to work. In this case, define GETLOADAVG_PRIVILEGED, set the output variable NEED_SETGID to ‘true’ (and otherwise to ‘false’), and set KMEM_GROUP to the name of the group that should own the installed program.

The AC_FUNC_GETLOADAVG macro is obsolescent. New programs should use Gnulib’s getloadavg module. See Gnulib.

Macro: AC_FUNC_GETMNTENT ¶

Check for getmntent in the standard C library, and then in the sun, seq, and gen libraries, for UNICOS, IRIX 4, PTX, and UnixWare, respectively. Then, if getmntent is available, define HAVE_GETMNTENT and set ac_cv_func_getmntent to yes. Otherwise set ac_cv_func_getmntent to no.

The result of this macro can be overridden by setting the cache variable ac_cv_search_getmntent.

The AC_FUNC_GETMNTENT macro is obsolescent. New programs should use Gnulib’s mountlist module. See Gnulib.

Macro: AC_FUNC_GETPGRP ¶

Define GETPGRP_VOID if it is an error to pass 0 to getpgrp; this is the Posix behavior. On older BSD systems, you must pass 0 to getpgrp, as it takes an argument and behaves like Posix’s getpgid.

#ifdef GETPGRP_VOID
  pid = getpgrp ();
#else
  pid = getpgrp (0);
#endif

This macro does not check whether getpgrp exists at all; if you need to work in that situation, first call AC_CHECK_FUNC for getpgrp.

The result of this macro is cached in the ac_cv_func_getpgrp_void variable.

This macro is obsolescent, as current systems have a getpgrp whose signature conforms to Posix. New programs need not use this macro.

Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK ¶

If link is a symbolic link, then lstat should treat link/ the same as link/.. However, many older lstat implementations incorrectly ignore trailing slashes.

It is safe to assume that if lstat incorrectly ignores trailing slashes, then other symbolic-link-aware functions like unlink also incorrectly ignore trailing slashes.

If lstat behaves properly, define LSTAT_FOLLOWS_SLASHED_SYMLINK, otherwise require an AC_LIBOBJ replacement of lstat.

The result of this macro is cached in the ac_cv_func_lstat_dereferences_slashed_symlink variable.

The AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK macro is obsolescent. New programs should use Gnulib’s lstat module. See Gnulib.

Macro: AC_FUNC_MALLOC ¶

If the malloc function is compatible with the GNU C library malloc (i.e., ‘malloc (0)’ returns a valid pointer), define HAVE_MALLOC to 1. Otherwise define HAVE_MALLOC to 0, ask for an AC_LIBOBJ replacement for ‘malloc’, and define malloc to rpl_malloc so that the native malloc is not used in the main project.

Typically, the replacement file malloc.c should look like (note the ‘#undef malloc’):

#include <config.h>
#undef malloc

#include <stdlib.h>

/* Allocate an N-byte block of memory from the heap.
   If N is zero, allocate a 1-byte block.  */

void *
rpl_malloc (size_t n)
{
  if (n == 0)
    n = 1;
  return malloc (n);
}

The result of this macro is cached in the ac_cv_func_malloc_0_nonnull variable.

If you don’t want to maintain a malloc.c file in your package manually, you can instead use the Gnulib module malloc-gnu.

Macro: AC_FUNC_MBRTOWC ¶

Define HAVE_MBRTOWC to 1 if the function mbrtowc and the type mbstate_t are properly declared.

The result of this macro is cached in the ac_cv_func_mbrtowc variable.

The Gnulib module mbrtowc not only ensures that the function is declared, but also works around other portability problems of this function.

Macro: AC_FUNC_MEMCMP ¶

If the memcmp function is not available or does not work, require an AC_LIBOBJ replacement for ‘memcmp’.

The result of this macro is cached in the ac_cv_func_memcmp_working variable.

This macro is obsolescent, as current systems have a working memcmp. New programs need not use this macro.

Macro: AC_FUNC_MKTIME ¶

If the mktime function is not available, or does not work correctly, require an AC_LIBOBJ replacement for ‘mktime’. For the purposes of this test, mktime should conform to the Posix standard and should be the inverse of localtime.

The result of this macro is cached in the ac_cv_func_working_mktime variable.

The AC_FUNC_MKTIME macro is obsolescent. New programs should use Gnulib’s mktime module. See Gnulib.

Macro: AC_FUNC_MMAP ¶

If the mmap function exists and works correctly, define HAVE_MMAP. This checks only private fixed mapping of already-mapped memory.

The result of this macro is cached in the ac_cv_func_mmap_fixed_mapped variable.

Note: This macro asks for more than what an average program needs from mmap. In particular, the use of MAP_FIXED fails on HP-UX 11, whereas mmap otherwise works fine on this platform.

Macro: AC_FUNC_OBSTACK ¶

If the obstacks are found, define HAVE_OBSTACK, else require an AC_LIBOBJ replacement for ‘obstack’.

The result of this macro is cached in the ac_cv_func_obstack variable.

The AC_FUNC_OBSTACK macro is obsolescent. New programs should use Gnulib’s obstack module. See Gnulib.

Macro: AC_FUNC_REALLOC ¶

If the realloc function is compatible with the GNU C library realloc (i.e., ‘realloc (NULL, 0)’ returns a valid pointer), define HAVE_REALLOC to 1. Otherwise define HAVE_REALLOC to 0, ask for an AC_LIBOBJ replacement for ‘realloc’, and define realloc to rpl_realloc so that the native realloc is not used in the main project. See AC_FUNC_MALLOC for details.

The result of this macro is cached in the ac_cv_func_realloc_0_nonnull variable.

If you don’t want to maintain a realloc.c file in your package manually, you can instead use the Gnulib module realloc-gnu.

Macro: AC_FUNC_SELECT_ARGTYPES ¶

Determines the correct type to be passed for each of the select function’s arguments, and defines those types in SELECT_TYPE_ARG1, SELECT_TYPE_ARG234, and SELECT_TYPE_ARG5 respectively. SELECT_TYPE_ARG1 defaults to ‘int’, SELECT_TYPE_ARG234 defaults to ‘int *’, and SELECT_TYPE_ARG5 defaults to ‘struct timeval *’.

This macro is obsolescent, as current systems have a select whose signature conforms to Posix. New programs need not use this macro.

Macro: AC_FUNC_SETPGRP ¶

If setpgrp takes no argument (the Posix version), define SETPGRP_VOID. Otherwise, it is the BSD version, which takes two process IDs as arguments. This macro does not check whether setpgrp exists at all; if you need to work in that situation, first call AC_CHECK_FUNC for setpgrp. This macro also does not check for the Solaris variant of setpgrp, which returns a pid_t instead of an int; portable code should only use the return value by comparing it against -1 to check for errors.

The result of this macro is cached in the ac_cv_func_setpgrp_void variable.

This macro is obsolescent, as all forms of setpgrp are also obsolescent. New programs should use the Posix function setpgid, which takes two process IDs as arguments (like the BSD setpgrp).

Macro: AC_FUNC_STAT ¶

Macro: AC_FUNC_LSTAT ¶

Determine whether stat or lstat have the bug that it succeeds when given the zero-length file name as argument.

If it does, then define HAVE_STAT_EMPTY_STRING_BUG (or HAVE_LSTAT_EMPTY_STRING_BUG) and ask for an AC_LIBOBJ replacement of it.

The results of these macros are cached in the ac_cv_func_stat_empty_string_bug and the ac_cv_func_lstat_empty_string_bug variables, respectively.

These macros are obsolescent, as no current systems have the bug. New programs need not use these macros.

Macro: AC_FUNC_STRCOLL ¶

If the strcoll function exists and works correctly, define HAVE_STRCOLL. This does a bit more than ‘AC_CHECK_FUNCS(strcoll)’, because some systems have incorrect definitions of strcoll that should not be used. But it does not check against a known bug of this function on Solaris 10.

The result of this macro is cached in the ac_cv_func_strcoll_works variable.

Macro: AC_FUNC_STRERROR_R ¶

If strerror_r is available, define HAVE_STRERROR_R, and if it is declared, define HAVE_DECL_STRERROR_R. If it returns a char * message, define STRERROR_R_CHAR_P; otherwise it returns an int error number. The Thread-Safe Functions option of Posix requires strerror_r to return int, but many systems (including, for example, version 2.2.4 of the GNU C Library) return a char * value that is not necessarily equal to the buffer argument.

The result of this macro is cached in the ac_cv_func_strerror_r_char_p variable.

The Gnulib module strerror_r not only ensures that the function has the return type specified by Posix, but also works around other portability problems of this function.

Macro: AC_FUNC_STRFTIME ¶

Check for strftime in the intl library, for SCO Unix. Then, if strftime is available, define HAVE_STRFTIME.

This macro is obsolescent, as no current systems require the intl library for strftime. New programs need not use this macro.

Macro: AC_FUNC_STRTOD ¶

If the strtod function does not exist or doesn’t work correctly, ask for an AC_LIBOBJ replacement of ‘strtod’. In this case, because strtod.c is likely to need ‘pow’, set the output variable POW_LIB to the extra library needed.

This macro caches its result in the ac_cv_func_strtod variable and depends upon the result in the ac_cv_func_pow variable.

The AC_FUNC_STRTOD macro is obsolescent. New programs should use Gnulib’s strtod module. See Gnulib.

Macro: AC_FUNC_STRTOLD ¶

If the strtold function exists and conforms to C99 or later, define HAVE_STRTOLD.

This macro caches its result in the ac_cv_func_strtold variable.

The Gnulib module strtold not only ensures that the function exists, but also works around other portability problems of this function.

Macro: AC_FUNC_STRNLEN ¶

If the strnlen function is not available, or is buggy (like the one from AIX 4.3), require an AC_LIBOBJ replacement for it.

This macro caches its result in the ac_cv_func_strnlen_working variable.

The AC_FUNC_STRNLEN macro is obsolescent. New programs should use Gnulib’s strnlen module. See Gnulib.

Macro: AC_FUNC_UTIME_NULL ¶

If ‘utime (file, NULL)’ sets file’s timestamp to the present, define HAVE_UTIME_NULL.

This macro caches its result in the ac_cv_func_utime_null variable.

This macro is obsolescent, as all current systems have a utime that behaves this way. New programs need not use this macro.

Macro: AC_FUNC_VPRINTF ¶

If vprintf is found, define HAVE_VPRINTF. Otherwise, if _doprnt is found, define HAVE_DOPRNT. (If vprintf is available, you may assume that vfprintf and vsprintf are also available.)

This macro is obsolescent, as all current systems have vprintf. New programs need not use this macro.

Macro: AC_REPLACE_FNMATCH ¶

If the fnmatch function does not conform to Posix (see AC_FUNC_FNMATCH), ask for its AC_LIBOBJ replacement.

The files fnmatch.c, fnmatch_loop.c, and fnmatch_.h in the AC_LIBOBJ replacement directory are assumed to contain a copy of the source code of GNU fnmatch. If necessary, this source code is compiled as an AC_LIBOBJ replacement, and the fnmatch_.h file is linked to fnmatch.h so that it can be included in place of the system <fnmatch.h>.

This macro caches its result in the ac_cv_func_fnmatch_works variable.

This macro is obsolescent, as it assumes the use of particular source files. New programs should use Gnulib’s fnmatch-posix module, which provides this macro along with the source files. See Gnulib.

5.5.3 Generic Function Checks

These macros are used to find functions not covered by the “particular” test macros. If the functions might be in libraries other than the default C library, first call AC_CHECK_LIB for those libraries. If you need to check the behavior of a function as well as find out whether it is present, you have to write your own test for it (see Writing Tests).

Macro: AC_CHECK_FUNC (function, [action-if-found], [action-if-not-found]) ¶

If C function function is available, run shell commands action-if-found, otherwise action-if-not-found. If you just want to define a symbol if the function is available, consider using AC_CHECK_FUNCS instead. This macro checks for functions with C linkage even when AC_LANG(C++) has been called, since C is more standardized than C++. (see Language Choice, for more information about selecting the language for checks.)

This macro caches its result in the ac_cv_func_function variable.

Macro: AC_CHECK_FUNCS (function…, [action-if-found], [action-if-not-found]) ¶

For each function enumerated in the blank-or-newline-separated argument list, define HAVE_function (in all capitals) if it is available. If action-if-found is given, it is additional shell code to execute when one of the functions is found. You can give it a value of ‘break’ to break out of the loop on the first match. If action-if-not-found is given, it is executed when one of the functions is not found.

Results are cached for each function as in AC_CHECK_FUNC.

Macro: AC_CHECK_FUNCS_ONCE (function…) ¶

For each function enumerated in the blank-or-newline-separated argument list, define HAVE_function (in all capitals) if it is available. This is a once-only variant of AC_CHECK_FUNCS. It generates the checking code at most once, so that configure is smaller and faster; but the checks cannot be conditionalized and are always done once, early during the configure run.

Autoconf follows a philosophy that was formed over the years by those who have struggled for portability: isolate the portability issues in specific files, and then program as if you were in a Posix environment. Some functions may be missing or unfixable, and your package must be ready to replace them.

Suitable replacements for many such problem functions are available from Gnulib (see Gnulib).

Macro: AC_LIBOBJ (function) ¶

Specify that ‘function.c’ must be included in the executables to replace a missing or broken implementation of function.

Technically, it adds ‘function.$ac_objext’ to the output variable LIBOBJS if it is not already in, and calls AC_LIBSOURCE for ‘function.c’. You should not directly change LIBOBJS, since this is not traceable.

Macro: AC_LIBSOURCE (file) ¶

Specify that file might be needed to compile the project. If you need to know what files might be needed by a configure.ac, you should trace AC_LIBSOURCE. file must be a literal.

This macro is called automatically from AC_LIBOBJ, but you must call it explicitly if you pass a shell variable to AC_LIBOBJ. In that case, since shell variables cannot be traced statically, you must pass to AC_LIBSOURCE any possible files that the shell variable might cause AC_LIBOBJ to need. For example, if you want to pass a variable $foo_or_bar to AC_LIBOBJ that holds either "foo" or "bar", you should do:

AC_LIBSOURCE([foo.c])
AC_LIBSOURCE([bar.c])
AC_LIBOBJ([$foo_or_bar])

There is usually a way to avoid this, however, and you are encouraged to simply call AC_LIBOBJ with literal arguments.

Note that this macro replaces the obsolete AC_LIBOBJ_DECL, with slightly different semantics: the old macro took the function name, e.g., foo, as its argument rather than the file name.

Macro: AC_LIBSOURCES (files) ¶

Like AC_LIBSOURCE, but accepts one or more files in a comma-separated M4 list. Thus, the above example might be rewritten:

AC_LIBSOURCES([foo.c, bar.c])
AC_LIBOBJ([$foo_or_bar])

Macro: AC_CONFIG_LIBOBJ_DIR (directory) ¶

Specify that AC_LIBOBJ replacement files are to be found in directory, a name relative to the top level of the source tree. The replacement directory defaults to ., the top level directory, and the most typical value is lib, corresponding to ‘AC_CONFIG_LIBOBJ_DIR([lib])’.

configure might need to know the replacement directory for the following reasons: (i) some checks use the replacement files, (ii) some macros bypass broken system headers by installing links to the replacement headers (iii) when used in conjunction with Automake, within each makefile, directory is used as a relative path from $(top_srcdir) to each object named in LIBOBJS and LTLIBOBJS, etc.

It is common to merely check for the existence of a function, and ask for its AC_LIBOBJ replacement if missing. The following macro is a convenient shorthand.

Macro: AC_REPLACE_FUNCS (function…) ¶

Like AC_CHECK_FUNCS, but uses ‘AC_LIBOBJ(function)’ as action-if-not-found. You can declare your replacement function by enclosing the prototype in ‘#ifndef HAVE_function’. If the system has the function, it probably declares it in a header file you should be including, so you shouldn’t redeclare it lest your declaration conflict.

5.6.1 Portability of Headers

This section documents some collected knowledge about common headers, and the problems they cause. By definition, this list always requires additions. A much more complete list is maintained by the Gnulib project (see Gnulib), covering Posix Headers in Gnulib and Glibc Headers in Gnulib. Please help us keep the Gnulib list as complete as possible.

When we say that a header “may require” some set of other headers, we mean that it may be necessary for you to manually include those other headers first, or the contents of the header under test will fail to compile. When checking for these headers, you must provide the potentially-required headers in the includes argument to AC_CHECK_HEADER or AC_CHECK_HEADERS, or the check will fail spuriously. AC_INCLUDES_DEFAULT (see Default Includes) arranges to include a number of common requirements and should normally come first in your includes. For example, net/if.h may require sys/types.h, sys/socket.h, or both, and AC_INCLUDES_DEFAULT handles sys/types.h but not sys/socket.h, so you should check for it like this:

AC_CHECK_HEADERS([sys/socket.h])
AC_CHECK_HEADERS([net/if.h], [], [],
[AC_INCLUDES_DEFAULT[
#ifdef HAVE_SYS_SOCKET_H
# include <sys/socket.h>
#endif
]])

Note that the example mixes single quoting (forAC_INCLUDES_DEFAULT, so that it gets expanded) and double quoting (to ensure that each preprocessor # gets treated as a literal string rather than a comment).

limits.h

In C99 and later, limits.h defines LLONG_MIN, LLONG_MAX, and ULLONG_MAX, but many almost-C99 environments (e.g., default GCC 4.0.2 + glibc 2.4) do not define them.

memory.h ¶

This header file is obsolete; use string.h instead.

strings.h ¶

On some systems, this is the only header that declares strcasecmp, strncasecmp, and ffs.

This header may or may not include string.h for you. However, on all recent systems it is safe to include both string.h and strings.h, in either order, in the same source file.

inttypes.h vs. stdint.h ¶

C99 specifies that inttypes.h includes stdint.h, so there’s no need to include stdint.h separately in a standard environment. However, some implementations have stdint.h but not inttypes.h (e.g. MSVC 2012). Therefore, it is necessary to check for each and include each only if available.

linux/irda.h ¶

This header may require linux/types.h and/or sys/socket.h.

linux/random.h ¶

This header may require linux/types.h.

net/if.h ¶

This header may require sys/types.h and/or sys/socket.h.

netinet/if_ether.h ¶

This header may require some combination of sys/types.h, sys/socket.h, netinet/in.h, and net/if.h.

sys/mount.h ¶

This header may require sys/params.h.

sys/ptem.h ¶

This header may require sys/stream.h.

sys/socket.h ¶

This header may require sys/types.h.

sys/ucred.h ¶

This header may require sys/types.h.

X11/extensions/scrnsaver.h ¶

Using XFree86, this header requires X11/Xlib.h, which is probably so required that you might not even consider looking for it.

5.6.2 Particular Header Checks

These macros check for particular system header files—whether they exist, and in some cases whether they declare certain symbols.

Macro: AC_CHECK_HEADER_STDBOOL ¶

Check whether stdbool.h exists and conforms to C99 or later, and cache the result in the ac_cv_header_stdbool_h variable. If the type _Bool is defined, define HAVE__BOOL to 1.

This macro is obsolescent, as all current C compilers have stdbool.h, a header that is itself obsolescent as of C23.

This macro is intended for use by Gnulib (see Gnulib) and other packages that supply a substitute stdbool.h on platforms lacking a conforming one. The AC_HEADER_STDBOOL macro is better for code that explicitly checks for stdbool.h.

Macro: AC_HEADER_ASSERT ¶

Check whether to enable assertions in the style of assert.h. Assertions are enabled by default, but the user can override this by invoking configure with the --disable-assert option.

Macro: AC_HEADER_DIRENT ¶

Check for the following header files. For the first one that is found and defines ‘DIR’, define the listed C preprocessor macro:

dirent.h	HAVE_DIRENT_H
sys/ndir.h	HAVE_SYS_NDIR_H
sys/dir.h	HAVE_SYS_DIR_H
ndir.h	HAVE_NDIR_H

The directory-library declarations in your source code should look something like the following:

#include <sys/types.h>
#ifdef HAVE_DIRENT_H
# include <dirent.h>
# define NAMLEN(dirent) strlen ((dirent)->d_name)
#else
# define dirent direct
# define NAMLEN(dirent) ((dirent)->d_namlen)
# ifdef HAVE_SYS_NDIR_H
#  include <sys/ndir.h>
# endif
# ifdef HAVE_SYS_DIR_H
#  include <sys/dir.h>
# endif
# ifdef HAVE_NDIR_H
#  include <ndir.h>
# endif
#endif

Using the above declarations, the program would declare variables to be of type struct dirent, not struct direct, and would access the length of a directory entry name by passing a pointer to a struct dirent to the NAMLEN macro.

This macro also checks for the SCO Xenix dir and x libraries.

This macro is obsolescent, as all current systems with directory libraries have <dirent.h>. New programs need not use this macro.

Also see AC_STRUCT_DIRENT_D_INO and AC_STRUCT_DIRENT_D_TYPE (see Particular Structure Checks).

Macro: AC_HEADER_MAJOR ¶

Detect the headers required to use makedev, major, and minor. These functions may be defined by sys/mkdev.h, sys/sysmacros.h, or sys/types.h.

AC_HEADER_MAJOR defines MAJOR_IN_MKDEV if they are in sys/mkdev.h, or MAJOR_IN_SYSMACROS if they are in sys/sysmacros.h. If neither macro is defined, they are either in sys/types.h or unavailable.

To properly use these functions, your code should contain something like:

#include <sys/types.h>
#ifdef MAJOR_IN_MKDEV
# include <sys/mkdev.h>
#elif defined MAJOR_IN_SYSMACROS
# include <sys/sysmacros.h>
#endif

Note: Configure scripts built with Autoconf 2.69 or earlier will not detect a problem if sys/types.h contains definitions of major, minor, and/or makedev that trigger compiler warnings upon use. This is known to occur with GNU libc 2.25, where those definitions are being deprecated to reduce namespace pollution. If it is not practical to use Autoconf 2.70 to regenerate the configure script of affected software, you can work around the problem by setting ‘ac_cv_header_sys_types_h_makedev=no’, as an argument to configure or as part of a config.site site default file (see Setting Site Defaults).

Macro: AC_HEADER_RESOLV ¶

Checks for header resolv.h, checking for prerequisites first. To properly use resolv.h, your code should contain something like the following:

#ifdef HAVE_SYS_TYPES_H
#  include <sys/types.h>
#endif
#ifdef HAVE_NETINET_IN_H
#  include <netinet/in.h>   /* inet_ functions / structs */
#endif
#ifdef HAVE_ARPA_NAMESER_H
#  include <arpa/nameser.h> /* DNS HEADER struct */
#endif
#ifdef HAVE_NETDB_H
#  include <netdb.h>
#endif
#include <resolv.h>

Macro: AC_HEADER_STAT ¶

If the macros S_ISDIR, S_ISREG, etc. defined in sys/stat.h do not work properly (returning false positives), define STAT_MACROS_BROKEN. This is the case on Tektronix UTekV, Amdahl UTS and Motorola System V/88.

This macro is obsolescent, as no current systems have the bug. New programs need not use this macro.

Macro: AC_HEADER_STDBOOL ¶

If stdbool.h exists and conforms to C99 or later, define HAVE_STDBOOL_H to 1; if the type _Bool is defined, define HAVE__BOOL to 1.

This macro is obsolescent, as all current C compilers have stdbool.h, a header that is itself obsolescent as of C23. Nowadays programs that need bool, true and false can include stdbool.h unconditionally, without using AC_HEADER_STDBOOL, and if such a program needs to be portable only to C23 or later it need not even include stdbool.h.

This macro caches its result in the ac_cv_header_stdbool_h variable.

This macro differs from AC_CHECK_HEADER_STDBOOL only in that it defines HAVE_STDBOOL_H whereas AC_CHECK_HEADER_STDBOOL does not.

Macro: AC_HEADER_STDC ¶

This macro is obsolescent. Its sole effect is to make sure that all the headers that are included by AC_INCLUDES_DEFAULT (see Default Includes), but not part of C89, have been checked for.

All hosted environments that are still of interest for portable code provide all of the headers specified in C89 (as amended in 1995).

Macro: AC_HEADER_SYS_WAIT ¶

If sys/wait.h exists and is compatible with Posix, define HAVE_SYS_WAIT_H. Incompatibility can occur if sys/wait.h does not exist, or if it uses the old BSD union wait instead of int to store a status value. If sys/wait.h is not Posix compatible, then instead of including it, define the Posix macros with their usual interpretations. Here is an example:

#include <sys/types.h>
#ifdef HAVE_SYS_WAIT_H
# include <sys/wait.h>
#endif
#ifndef WEXITSTATUS
# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
#endif
#ifndef WIFEXITED
# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
#endif

This macro caches its result in the ac_cv_header_sys_wait_h variable.

This macro is obsolescent, as current systems are compatible with Posix. New programs need not use this macro.

_POSIX_VERSION is defined when unistd.h is included on Posix systems. If there is no unistd.h, it is definitely not a Posix system. However, some non-Posix systems do have unistd.h.

The way to check whether the system supports Posix is:

#ifdef HAVE_UNISTD_H
# include <sys/types.h>
# include <unistd.h>
#endif

#ifdef _POSIX_VERSION
/* Code for Posix systems.  */
#endif

Macro: AC_HEADER_TIOCGWINSZ ¶

If the use of TIOCGWINSZ requires <sys/ioctl.h>, then define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be found in <termios.h>.

Use:

#ifdef HAVE_TERMIOS_H
# include <termios.h>
#endif

#ifdef GWINSZ_IN_SYS_IOCTL
# include <sys/ioctl.h>
#endif

5.6.3 Generic Header Checks

These macros are used to find system header files not covered by the “particular” test macros. If you need to check the contents of a header as well as find out whether it is present, you have to write your own test for it (see Writing Tests).

Macro: AC_CHECK_HEADER (header-file, [action-if-found], [action-if-not-found], [includes]) ¶

If the system header file header-file is compilable, execute shell commands action-if-found, otherwise execute action-if-not-found. If you just want to define a symbol if the header file is available, consider using AC_CHECK_HEADERS instead.

includes should be the appropriate prerequisite code, i.e. whatever might be required to appear above ‘#include <header-file>’ for it to compile without error. This can be anything, but will normally be additional ‘#include’ directives. If includes is omitted or empty, configure will use the contents of the macro AC_INCLUDES_DEFAULT. See Default Includes.

This macro used to check only for the presence of a header, not whether its contents were acceptable to the compiler. Some older configure scripts rely on this behavior, so it is still available by specifying ‘-’ as includes. This mechanism is deprecated as of Autoconf 2.70; situations where a preprocessor-only check is required should use AC_PREPROC_IFELSE. See Running the Preprocessor.

This macro caches its result in the ac_cv_header_header-file variable, with characters not suitable for a variable name mapped to underscores.

Macro: AC_CHECK_HEADERS (header-file…, [action-if-found], [action-if-not-found], [includes]) ¶

For each given system header file header-file in the blank-separated argument list that exists, define HAVE_header-file (in all capitals). If action-if-found is given, it is additional shell code to execute when one of the header files is found. You can give it a value of ‘break’ to break out of the loop on the first match. If action-if-not-found is given, it is executed when one of the header files is not found.

includes is interpreted as in AC_CHECK_HEADER, in order to choose the set of preprocessor directives supplied before the header under test.

This macro caches its result in the ac_cv_header_header-file variable, with characters not suitable for a variable name mapped to underscores.

Macro: AC_CHECK_HEADERS_ONCE (header-file…) ¶

For each given system header file header-file in the blank-separated argument list that exists, define HAVE_header-file (in all capitals).

If you do not need the full power of AC_CHECK_HEADERS, this variant generates smaller, faster configure files. All headers passed to AC_CHECK_HEADERS_ONCE are checked for in one pass, early during the configure run. The checks cannot be conditionalized, you cannot specify an action-if-found or action-if-not-found, and AC_INCLUDES_DEFAULT is always used for the prerequisites.

In previous versions of Autoconf, these macros merely checked whether the header was accepted by the preprocessor. This was changed because the old test was inappropriate for typical uses. Headers are typically used to compile, not merely to preprocess, and the old behavior sometimes accepted headers that clashed at compile-time (see Header Present But Cannot Be Compiled). If for some reason it is inappropriate to check whether a header is compilable, you should use AC_PREPROC_IFELSE (see Running the Preprocessor) instead of these macros.

Requiring each header to compile improves the robustness of the test, but it also requires you to make sure that the includes are correct. Most system headers nowadays make sure to #include whatever they require, or else have their dependencies satisfied by AC_INCLUDES_DEFAULT (see Default Includes), but see Portability of Headers, for known exceptions. In general, if you are looking for bar.h, which requires that foo.h be included first if it exists, you should do something like this:

AC_CHECK_HEADERS([foo.h])
AC_CHECK_HEADERS([bar.h], [], [],
[#ifdef HAVE_FOO_H
# include <foo.h>
#endif
])

5.7.1 Particular Declaration Checks

There are no specific macros for declarations.

5.7.2 Generic Declaration Checks

These macros are used to find declarations not covered by the “particular” test macros.

Macro: AC_CHECK_DECL (symbol, [action-if-found], [action-if-not-found], [includes = ‘AC_INCLUDES_DEFAULT’]) ¶

If symbol (a function, variable, or constant) is not declared in includes and a declaration is needed, run the shell commands action-if-not-found, otherwise action-if-found. includes is a series of include directives, defaulting to AC_INCLUDES_DEFAULT (see Default Includes), which are used prior to the declaration under test.

This macro actually tests whether symbol is defined as a macro or can be used as an r-value, not whether it is really declared, because it is much safer to avoid introducing extra declarations when they are not needed. In order to facilitate use of C++ and overloaded function declarations, it is possible to specify function argument types in parentheses for types which can be zero-initialized:

AC_CHECK_DECL([basename(char *)])

This macro caches its result in the ac_cv_have_decl_symbol variable, with characters not suitable for a variable name mapped to underscores.

Macro: AC_CHECK_DECLS (symbols, [action-if-found], [action-if-not-found], [includes = ‘AC_INCLUDES_DEFAULT’]) ¶

For each of the symbols (comma-separated list with optional function argument types for C++ overloads), define HAVE_DECL_symbol (in all capitals) to ‘1’ if symbol is declared, otherwise to ‘0’. If action-if-not-found is given, it is additional shell code to execute when one of the function declarations is needed, otherwise action-if-found is executed.

includes is a series of include directives, defaulting to AC_INCLUDES_DEFAULT (see Default Includes), which are used prior to the declarations under test.

This macro uses an M4 list as first argument:

AC_CHECK_DECLS([strdup])
AC_CHECK_DECLS([strlen])
AC_CHECK_DECLS([malloc, realloc, calloc, free])
AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]])
AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]])

Unlike the other ‘AC_CHECK_*S’ macros, when a symbol is not declared, HAVE_DECL_symbol is defined to ‘0’ instead of leaving HAVE_DECL_symbol undeclared. When you are sure that the check was performed, use HAVE_DECL_symbol in #if:

#if !HAVE_DECL_SYMBOL
extern char *symbol;
#endif

If the test may have not been performed, however, because it is safer not to declare a symbol than to use a declaration that conflicts with the system’s one, you should use:

#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
void *malloc (size_t *s);
#endif

You fall into the second category only in extreme situations: either your files may be used without being configured, or they are used during the configuration. In most cases the traditional approach is enough.

This macro caches its results in ac_cv_have_decl_symbol variables, with characters not suitable for a variable name mapped to underscores.

Macro: AC_CHECK_DECLS_ONCE (symbols) ¶

For each of the symbols (comma-separated list), define HAVE_DECL_symbol (in all capitals) to ‘1’ if symbol is declared in the default include files, otherwise to ‘0’. This is a once-only variant of AC_CHECK_DECLS. It generates the checking code at most once, so that configure is smaller and faster; but the checks cannot be conditionalized and are always done once, early during the configure run.

5.8.1 Particular Structure Checks

The following macros check for certain structures or structure members.

Macro: AC_STRUCT_DIRENT_D_INO ¶

Perform all the actions of AC_HEADER_DIRENT (see Particular Header Checks). Then, if struct dirent contains a d_ino member, define HAVE_STRUCT_DIRENT_D_INO.

HAVE_STRUCT_DIRENT_D_INO indicates only the presence of d_ino, not whether its contents are always reliable. Traditionally, a zero d_ino indicated a deleted directory entry, though current systems hide this detail from the user and never return zero d_ino values. Many current systems report an incorrect d_ino for a directory entry that is a mount point.

Macro: AC_STRUCT_DIRENT_D_TYPE ¶

Perform all the actions of AC_HEADER_DIRENT (see Particular Header Checks). Then, if struct dirent contains a d_type member, define HAVE_STRUCT_DIRENT_D_TYPE.

Macro: AC_STRUCT_ST_BLOCKS ¶

If struct stat contains an st_blocks member, define HAVE_STRUCT_STAT_ST_BLOCKS. Otherwise, require an AC_LIBOBJ replacement of ‘fileblocks’. The former name, HAVE_ST_BLOCKS is to be avoided, as its support will cease in the future.

This macro caches its result in the ac_cv_member_struct_stat_st_blocks variable.

Macro: AC_STRUCT_TM ¶

If time.h does not define struct tm, define TM_IN_SYS_TIME, which means that including sys/time.h had better define struct tm.

This macro is obsolescent, as time.h defines struct tm in current systems. New programs need not use this macro.

Macro: AC_STRUCT_TIMEZONE ¶

Figure out how to get the current timezone. If struct tm has a tm_zone member, define HAVE_STRUCT_TM_TM_ZONE (and the obsoleted HAVE_TM_ZONE). Otherwise, if the external array tzname is found, define HAVE_TZNAME; if it is declared, define HAVE_DECL_TZNAME.

5.8.2 Generic Structure Checks

These macros are used to find structure members not covered by the “particular” test macros.

Macro: AC_CHECK_MEMBER (aggregate.member, [action-if-found], [action-if-not-found], [includes = ‘AC_INCLUDES_DEFAULT’]) ¶

Check whether member is a member of the aggregate aggregate. If no includes are specified, the default includes are used (see Default Includes).

AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
                [AC_MSG_ERROR([we need 'passwd.pw_gecos'])],
                [[#include <pwd.h>]])

You can use this macro for submembers:

AC_CHECK_MEMBER(struct top.middle.bot)

This macro caches its result in the ac_cv_member_aggregate_member variable, with characters not suitable for a variable name mapped to underscores.

Macro: AC_CHECK_MEMBERS (members, [action-if-found], [action-if-not-found], [includes = ‘AC_INCLUDES_DEFAULT’]) ¶

Check for the existence of each ‘aggregate.member’ of members using the previous macro. When member belongs to aggregate, define HAVE_aggregate_member (in all capitals, with spaces and dots replaced by underscores). If action-if-found is given, it is executed for each of the found members. If action-if-not-found is given, it is executed for each of the members that could not be found.

includes is a series of include directives, defaulting to AC_INCLUDES_DEFAULT (see Default Includes), which are used prior to the members under test.

This macro uses M4 lists:

AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])

5.9.1 Particular Type Checks

These macros check for particular C types in sys/types.h, stdlib.h, stdint.h, inttypes.h and others, if they exist.

The Gnulib stdint module is an alternate way to define many of these symbols; it is useful if you prefer your code to assume a C99-or-better environment. See Gnulib.

Macro: AC_TYPE_GETGROUPS ¶

Define GETGROUPS_T to be whichever of gid_t or int is the base type of the array argument to getgroups.

This macro caches the base type in the ac_cv_type_getgroups variable.

Macro: AC_TYPE_INT8_T ¶

If stdint.h or inttypes.h does not define the type int8_t, define int8_t to a signed integer type that is exactly 8 bits wide and that uses two’s complement representation, if such a type exists. If you are worried about porting to hosts that lack such a type, you can use the results of this macro as follows:

#if HAVE_STDINT_H
# include <stdint.h>
#endif
#if defined INT8_MAX || defined int8_t
 code using int8_t
#else
 complicated alternative using >8-bit 'signed char'
#endif

This macro caches the type in the ac_cv_c_int8_t variable.

Macro: AC_TYPE_INT16_T ¶

This is like AC_TYPE_INT8_T, except for 16-bit integers.

Macro: AC_TYPE_INT32_T ¶

This is like AC_TYPE_INT8_T, except for 32-bit integers.

Macro: AC_TYPE_INT64_T ¶

This is like AC_TYPE_INT8_T, except for 64-bit integers.

Macro: AC_TYPE_INTMAX_T ¶

If stdint.h or inttypes.h defines the type intmax_t, define HAVE_INTMAX_T. Otherwise, define intmax_t to the widest signed integer type.

Macro: AC_TYPE_INTPTR_T ¶

If stdint.h or inttypes.h defines the type intptr_t, define HAVE_INTPTR_T. Otherwise, define intptr_t to a signed integer type wide enough to hold a pointer, if such a type exists.

Macro: AC_TYPE_LONG_DOUBLE ¶

If the C compiler supports a working long double type, define HAVE_LONG_DOUBLE. The long double type might have the same range and precision as double.

This macro caches its result in the ac_cv_type_long_double variable.

This macro is obsolescent, as current C compilers support long double. New programs need not use this macro.

Macro: AC_TYPE_LONG_DOUBLE_WIDER ¶

If the C compiler supports a working long double type with more range or precision than the double type, define HAVE_LONG_DOUBLE_WIDER.

This macro caches its result in the ac_cv_type_long_double_wider variable.

Macro: AC_TYPE_LONG_LONG_INT ¶

If the C compiler supports a working long long int type, define HAVE_LONG_LONG_INT. However, this test does not test long long int values in preprocessor #if expressions, because too many compilers mishandle such expressions. See Preprocessor Arithmetic.

This macro caches its result in the ac_cv_type_long_long_int variable.

Macro: AC_TYPE_MBSTATE_T ¶

Define HAVE_MBSTATE_T if <wchar.h> declares the mbstate_t type. Also, define mbstate_t to be a type if <wchar.h> does not declare it.

This macro caches its result in the ac_cv_type_mbstate_t variable.

Macro: AC_TYPE_MODE_T ¶

Define mode_t to a suitable type, if standard headers do not define it.

This macro caches its result in the ac_cv_type_mode_t variable.

Macro: AC_TYPE_OFF_T ¶

Define off_t to a suitable type, if standard headers do not define it.

This macro caches its result in the ac_cv_type_off_t variable.

Macro: AC_TYPE_PID_T ¶

Define pid_t to a suitable type, if standard headers do not define it.

This macro caches its result in the ac_cv_type_pid_t variable.

Macro: AC_TYPE_SIZE_T ¶

Define size_t to a suitable type, if standard headers do not define it.

This macro caches its result in the ac_cv_type_size_t variable.

Macro: AC_TYPE_SSIZE_T ¶

Define ssize_t to a suitable type, if standard headers do not define it.

This macro caches its result in the ac_cv_type_ssize_t variable.

Macro: AC_TYPE_UID_T ¶

Define uid_t and gid_t to suitable types, if standard headers do not define them.

This macro caches its result in the ac_cv_type_uid_t variable.

Macro: AC_TYPE_UINT8_T ¶

If stdint.h or inttypes.h does not define the type uint8_t, define uint8_t to an unsigned integer type that is exactly 8 bits wide, if such a type exists. This is like AC_TYPE_INT8_T, except for unsigned integers.

Macro: AC_TYPE_UINT16_T ¶

This is like AC_TYPE_UINT8_T, except for 16-bit integers.

Macro: AC_TYPE_UINT32_T ¶

This is like AC_TYPE_UINT8_T, except for 32-bit integers.

Macro: AC_TYPE_UINT64_T ¶

This is like AC_TYPE_UINT8_T, except for 64-bit integers.

Macro: AC_TYPE_UINTMAX_T ¶

If stdint.h or inttypes.h defines the type uintmax_t, define HAVE_UINTMAX_T. Otherwise, define uintmax_t to the widest unsigned integer type.

Macro: AC_TYPE_UINTPTR_T ¶

If stdint.h or inttypes.h defines the type uintptr_t, define HAVE_UINTPTR_T. Otherwise, define uintptr_t to an unsigned integer type wide enough to hold a pointer, if such a type exists.

Macro: AC_TYPE_UNSIGNED_LONG_LONG_INT ¶

If the C compiler supports a working unsigned long long int type, define HAVE_UNSIGNED_LONG_LONG_INT. However, this test does not test unsigned long long int values in preprocessor #if expressions, because too many compilers mishandle such expressions. See Preprocessor Arithmetic.

This macro caches its result in the ac_cv_type_unsigned_long_long_int variable.

5.9.2 Generic Type Checks

These macros are used to check for types not covered by the “particular” test macros.

Macro: AC_CHECK_TYPE (type, [action-if-found], [action-if-not-found], [includes = ‘AC_INCLUDES_DEFAULT’]) ¶

Check whether type is defined. It may be a compiler builtin type or defined by the includes. includes is a series of include directives, defaulting to AC_INCLUDES_DEFAULT (see Default Includes), which are used prior to the type under test.

In C, type must be a type-name, so that the expression ‘sizeof (type)’ is valid (but ‘sizeof ((type))’ is not). The same test is applied when compiling for C++, which means that in C++ type should be a type-id and should not be an anonymous ‘struct’ or ‘union’.

This macro caches its result in the ac_cv_type_type variable, with ‘*’ mapped to ‘p’ and other characters not suitable for a variable name mapped to underscores.

Macro: AC_CHECK_TYPES (types, [action-if-found], [action-if-not-found], [includes = ‘AC_INCLUDES_DEFAULT’]) ¶

For each type of the types that is defined, define HAVE_type (in all capitals). Each type must follow the rules of AC_CHECK_TYPE. If no includes are specified, the default includes are used (see Default Includes). If action-if-found is given, it is additional shell code to execute when one of the types is found. If action-if-not-found is given, it is executed when one of the types is not found.

This macro uses M4 lists:

AC_CHECK_TYPES([ptrdiff_t])
AC_CHECK_TYPES([unsigned long long int, uintmax_t])
AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]])

Autoconf, up to 2.13, used to provide to another version of AC_CHECK_TYPE, broken by design. In order to keep backward compatibility, a simple heuristic, quite safe but not totally, is implemented. In case of doubt, read the documentation of the former AC_CHECK_TYPE, see Obsolete Macros.