9.3 Defining C Preprocessor Symbols

A common action to take in response to a feature test is to define a C
preprocessor symbol indicating the results of the test. That is done by
calling AC_DEFINE or AC_DEFINE_UNQUOTED.

By default, AC_OUTPUT places the symbols defined by these macros
into the output variable DEFS, which contains an option
-Dsymbol=value for each symbol defined. Unlike in
Autoconf version 1, there is no variable DEFS defined while
configure is running. To check whether Autoconf macros have
already defined a certain C preprocessor symbol, test the value of the
appropriate cache variable, as in this example:

If AC_CONFIG_HEADERS has been called, then instead of creating
DEFS, AC_OUTPUT creates a header file by substituting the
correct values into #define statements in a template file.
See Defining Symbols for more information about this kind of
output.

Macro: AC_DEFINE(variable, value, [description])

Macro: AC_DEFINE(variable)

Define variable to value (verbatim), by defining a C
preprocessor macro for variable. variable should be a C
identifier, optionally suffixed by a parenthesized argument list to
define a C preprocessor macro with arguments. The macro argument list,
if present, should be a comma-separated list of C identifiers, possibly
terminated by an ellipsis ‘...’ if C99-or-later syntax is employed.
variable should not contain comments, white space, trigraphs,
backslash-newlines, universal character names, or non-ASCII
characters.

value may contain backslash-escaped newlines, which will be
preserved if you use AC_CONFIG_HEADERS but flattened if passed
via @DEFS@ (with no effect on the compilation, since the
preprocessor sees only one line in the first place). value should
not contain raw newlines. If you are not using
AC_CONFIG_HEADERS, value should not contain any ‘#’
characters, as make tends to eat them. To use a shell
variable, use AC_DEFINE_UNQUOTED instead.

description is only useful if you are using
AC_CONFIG_HEADERS. In this case, description is put into
the generated config.h.in as the comment before the macro define.
The following example defines the C preprocessor variable
EQUATION to be the string constant ‘"$a > $b"’:

AC_DEFINE([EQUATION], ["$a > $b"],
[Equation string.])

If neither value nor description are given, then
value defaults to 1 instead of to the empty string. This is for
backwards compatibility with older versions of Autoconf, but this usage
is obsolescent and may be withdrawn in future versions of Autoconf.

If the variable is a literal string, it is passed to
m4_pattern_allow (see Forbidden Patterns).

If multiple AC_DEFINE statements are executed for the same
variable name (not counting any parenthesized argument list),
the last one wins.

Macro: AC_DEFINE_UNQUOTED(variable, value, [description])

Macro: AC_DEFINE_UNQUOTED(variable)

Like AC_DEFINE, but three shell expansions are
performed—once—on variable and value: variable expansion
(‘$’), command substitution (‘`’), and backslash escaping
(‘\’), as if in an unquoted here-document. Single and double quote
characters in the value have no
special meaning. Use this macro instead of AC_DEFINE when
variable or value is a shell variable. Examples:

Due to a syntactical bizarreness of the Bourne shell, do not use
semicolons to separate AC_DEFINE or AC_DEFINE_UNQUOTED
calls from other macro calls or shell code; that can cause syntax errors
in the resulting configure script. Use either blanks or
newlines. That is, do this:

When a package contains more than a few tests that define C preprocessor
symbols, the command lines to pass -D options to the compiler
can get quite long. This causes two problems. One is that the
make output is hard to visually scan for errors. More
seriously, the command lines can exceed the length limits of some
operating systems. As an alternative to passing -D options to
the compiler, configure scripts can create a C header file
containing ‘#define’ directives. The AC_CONFIG_HEADERS
macro selects this kind of output. Though it can be called anywhere
between AC_INIT and AC_OUTPUT, it is customary to call
it right after AC_INIT.

The package should ‘#include’ the configuration header file before
any other header files, to prevent inconsistencies in declarations (for
example, if it redefines const).

To provide for VPATH builds, remember to pass the C compiler a -I.
option (or -I..; whichever directory contains config.h).
Even if you use ‘#include "config.h"’, the preprocessor searches only
the directory of the currently read file, i.e., the source directory, not
the build directory.

With the appropriate -I option, you can use
‘#include <config.h>’. Actually, it’s a good habit to use it,
because in the rare case when the source directory contains another
config.h, the build directory should be searched first.

Macro: AC_CONFIG_HEADERS(header …, [cmds], [init-cmds])

This macro is one of the instantiating macros; see Configuration Actions. Make AC_OUTPUT create the file(s) in the
blank-or-newline-separated list header containing C preprocessor
#define statements, and replace ‘@DEFS@’ in generated
files with -DHAVE_CONFIG_H instead of the value of DEFS.
The usual name for header is config.h.

If header already exists and its contents are identical to what
AC_OUTPUT would put in it, it is left alone. Doing this allows
making some changes in the configuration without needlessly causing
object files that depend on the header file to be recompiled.

Usually the input file is named header.in; however, you can
override the input file name by appending to header a
colon-separated list of input files. For example, you might need to make
the input file name acceptable to DOS variants:

AC_CONFIG_HEADERS([config.h:config.hin])

Macro: AH_HEADER

This macro is defined as the name of the first declared config header
and undefined if no config headers have been declared up to this point.
A third-party macro may, for example, require use of a config header
without invoking AC_CONFIG_HEADERS twice, like this: