** Documentation:
* Autoconf manual is reorganized to make information easier to find
and has several new indexes.
+* INSTALL is reorganized and clearer and is now made from Texinfo source.
\f
Major changes in release 1.11:
* Making configure Scripts:: How to organize and produce Autoconf scripts.
* Operation:: Controlling Autoconf operation.
* Existing Tests:: Macros that check for particular features.
-* Primitives:: Macros used to build other checks.
-* Writing Macros:: How to add your own macros to Autoconf.
+* Makefiles:: Information Autoconf uses in @file{Makefile}s.
+* Writing Tests:: How to write new feature checks.
+* Writing Macros:: Adding new macros to Autoconf.
* Caching Values:: Speeding up subsequent @code{configure} runs.
* Manual Configuration:: Selecting features that can't be guessed.
-* Makefiles:: Information Autoconf uses in @file{Makefile}s.
* Invoking configure:: How to use the Autoconf output.
* Invoking config.status:: Recreating a configuration.
* Site Default Values:: Providing local defaults for @code{configure}.
* Particular Functions:: Special handling to find certain functions.
* Generic Functions:: How to find other functions.
-Primitives For Building Tests
+Makefiles
+
+* Predefined Variables:: Output variables that are always set.
+* VPATH Substitutions:: Compiling in a different directory.
+* Automatic Remaking:: Makefile rules for configuring.
+
+Writing Tests
-* C System Output:: Checking output of the C compiler system.
+* Checking for Symbols:: Finding whether a symbol is defined.
+* Test Programs:: Testing for run-time features.
+* Portable Shell:: Shell script portability pitfalls.
+* Testing Values and Files:: Checking strings and files.
+* Multiple Cases:: Tests for several possible values.
+* Defining Symbols:: Defining C preprocessor symbols.
* Setting Variables:: Setting shell and output variables.
* Printing Messages:: Notifying users of progress or problems.
* Language Choice:: Selecting which language to use for testing.
+Test Programs
+
+* Alternatives:: Approaches preferred over test programs.
+* Guidelines:: General rules for writing test programs.
+* Test Functions:: Avoiding pitfalls in test programs.
+
Writing Macros
* Macro Format:: Basic format of an Autoconf macro.
* Macro Naming:: What to call your new macros.
* Quoting:: Protecting macros from unwanted expansion.
* Dependencies Between Macros:: What to do when macros depend on other macros.
-* Portable Shell:: Shell script portability pitfalls.
-* Checking for Files:: Finding whether a file exists.
-* Checking for Symbols:: Finding whether a symbol is defined.
-* Test Programs:: Writing programs to test for features.
-* Multiple Cases:: Tests for several possible values.
Dependencies Between Macros
* Suggested Ordering:: Warning about possible ordering problems.
* Obsolete Macros:: Warning about old ways of doing things.
-Test Programs
-
-* Alternatives:: Approaches preferred over test programs.
-* Guidelines:: General rules for writing test programs.
-* Test Functions:: Special ways to work around problems.
-
Caching Values
* Cache Files:: Files @code{configure} uses for caching.
* System Name Variables:: Variables containing the system type.
* Using System Type:: What to do with the system type.
-Makefiles
-
-* Predefined Variables:: Output variables that are always set.
-* VPATH Substitutions:: Compiling in a different directory.
-* Automatic Remaking:: Makefile rules for configuring.
-
Running @code{configure} Scripts
* Basic Installation:: Instructions for typical cases.
use. Autoconf macros already exist to check for many features; see
@ref{Existing Tests}, for their descriptions. For most other
features, you can use Autoconf template macros to produce custom checks;
-see @ref{Primitives}, for information about them. For especially
+see @ref{Writing Tests}, for information about them. For especially
tricky or specialized features, @file{configure.in} might need to
contain some hand-crafted shell commands. @xref{Writing Macros}, for
guidelines on writing tests from scratch.
@node Output, Package Options, Input, Operation
@section Controlling Autoconf Output
-The following macros control the kind of output that Autoconf produces.
+The following macros control which files Autoconf creates.
@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{})
@maindex CONFIG_HEADER
@end example
@end defmac
-@node Existing Tests, Primitives, Operation, Top
+@node Existing Tests, Makefiles, Operation, Top
@chapter Existing Tests
These macros test for particular system features that packages
might need or want to use. If you need to test for a kind of feature
that none of these macros check for, you can probably do it by calling
-primitive test macros with appropriate arguments (@pxref{Primitives}).
+primitive test macros with appropriate arguments (@pxref{Writing Tests}).
Some of these macros set variables whose values can be substituted into
output files. @xref{Setting Variables}, for details on how this is
@section Structures
The following macros check for certain structures or structure members.
-You can use @code{AC_TRY_LINK} (@pxref{C System Output}) to check
+You can use @code{AC_TRY_LINK} (@pxref{Checking for Symbols}) to check
structures not listed here.
@defmac AC_HEADER_STAT
@section Compiler Characteristics
The following macros check for C compiler or machine architecture
-features. You can use @code{AC_TRY_LINK} or @code{AC_TRY_RUN} (@pxref{C
-System Output}) to check for characteristics not listed here.
+features. You can use @code{AC_TRY_LINK} (@pxref{Checking for Symbols})
+or @code{AC_TRY_RUN} (@pxref{Test Programs}) to check for
+characteristics not listed here.
@defmac AC_C_BIGENDIAN
@maindex C_BIGENDIAN
variable @code{cross_compiling} to @samp{yes}, otherwise @samp{no}.
This information can be used by @code{AC_TRY_RUN} to determine whether
to take a default action instead of trying to run a test program
-(@pxref{C System Output}). For more information on dealing with
-cross-compiling, @xref{Alternatives}.
+For more information on dealing with test programs and
+cross-compiling, @xref{Test Programs}.
@end defmac
@defmac AC_C_INLINE
@code{AC_DIR_HEADER} if it has not been called already.
@end defmac
-@node Primitives, Writing Macros, Existing Tests, Top
-@chapter Primitives For Building Tests
+@node Makefiles, Writing Tests, Existing Tests, Top
+@chapter Makefiles
+
+Each subdirectory in a distribution should come with a file
+@file{Makefile.in}, from which @code{configure} will produce a
+@file{Makefile} in that directory. The substitutions that
+@code{configure} does are simple: for each output variable that the
+package sets, it replaces occurrences of @samp{@@@var{variable}@@} with
+the value that @code{configure} has determined for that variable. Any
+occurrences of @samp{@@@var{variable}@@} for variables that
+@code{configure} does not know about are passed through unchanged.
+
+Every variable that the @code{configure} script might set a value for
+should appear in a @samp{@@@var{variable}@@} reference in at least one
+@file{Makefile.in}. There is no point in checking for the correct value
+to give a variable that is never used.
+
+@xref{Makefile Conventions, , Makefile Conventions, standards.info, The
+GNU Coding Standards}, for more information on what to put in Makefiles.
+
+@menu
+* Predefined Variables:: Output variables that are always set.
+* VPATH Substitutions:: Compiling in a different directory.
+* Automatic Remaking:: Makefile rules for configuring.
+@end menu
+
+@node Predefined Variables, VPATH Substitutions, , Makefiles
+@section Predefined Variables
+
+Some output variables are predefined by the Autoconf macros.
+@code{AC_SUBST} is called for them automatically (@pxref{Setting
+Variables}), so in your @file{Makefile.in} files you can get their
+values by enclosing their names in @samp{@@} characters.
+@ifinfo
+@xref{Makefiles}, for more information on @samp{@@} substitutions.
+@end ifinfo
+The variables that are automatically defined by the Autoconf macros are
+listed here. Some of the Autoconf macros define additional variables,
+which are mentioned in the descriptions for those macros. @xref{Output
+Variable Index}, for a complete list of output variables.
+
+@defvar exec_prefix
+@ovindex exec_prefix
+The installation prefix for architecture-specific files.
+@end defvar
+
+@defvar prefix
+@ovindex prefix
+The installation prefix for architecture-independent files.
+@end defvar
+
+@defvar srcdir
+@ovindex srcdir
+The directory that contains the source code for that @file{Makefile}.
+@end defvar
+
+@defvar top_srcdir
+@ovindex top_srcdir
+The top-level source code directory for the package. In the top-level
+directory, this is the same as @code{srcdir}.
+@end defvar
+
+@defvar CFLAGS
+@ovindex CFLAGS
+Debugging and optimization options for the C compiler. If it is not set
+in the environment when @code{configure} runs, the default value is set
+when you call @code{AC_PROG_CC} (or empty if you don't). @code{configure}
+uses this variable when compiling programs to test for C features.
+@end defvar
+
+@defvar CPPFLAGS
+@ovindex CPPFLAGS
+Header file search directory (@samp{-I@var{dir}}) and any other
+miscellaneous options for the C preprocessor and compiler. If it is not
+set in the environment when @code{configure} runs, the default value is
+empty. @code{configure} uses this variable when compiling or
+preprocessing programs to test for C features.
+@end defvar
+
+@defvar CXXFLAGS
+@ovindex CXXFLAGS
+Debugging and optimization options for the C++ compiler. If it is not
+set in the environment when @code{configure} runs, the default value is
+set when you call @code{AC_PROG_CXX} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+C++ features.
+@end defvar
+
+@defvar DEFS
+@ovindex DEFS
+@samp{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADER}
+is called, @code{configure} replaces @samp{@@DEFS@@} with
+@samp{-DHAVE_CONFIG_H} instead. This variable is not defined while
+@code{configure} is performing its tests, only when creating the output
+files. @xref{Setting Variables}, for more information.
+@end defvar
+
+@defvar LDFLAGS
+@ovindex LDFLAGS
+Stripping (@samp{-s}) and any other miscellaneous options for the
+linker. If it is not set in the environment when @code{configure} runs,
+the default value is empty. @code{configure} uses this variable when
+linking programs to test for C features.
+@end defvar
+
+@defvar LIBS
+@ovindex LIBS
+@samp{-l} and @samp{-L} options to pass to the linker.
+@end defvar
+
+@node VPATH Substitutions, Automatic Remaking, Predefined Variables, Makefiles
+@section @code{VPATH} Substitutions
+
+You might want to compile a software package in a different directory
+from the one that contains the source code. Doing this allows you to
+compile the package for several architectures simultaneously from the
+same copy of the source code and keep multiple sets of object files on
+disk.
+
+To support doing this, @code{make} uses the @code{VPATH} variable to
+find the files that are in the source directory. GNU @code{make} and
+most other recent @code{make} programs can do this. Older @code{make}
+programs do not support @code{VPATH}; when using them, the source code
+must be in the same directory as the object files.
+
+To support @code{VPATH}, each @file{Makefile.in} should contain two
+lines that look like:
+
+@example
+srcdir = @@srcdir@@
+VPATH = @@srcdir@@
+@end example
+
+Do not set @code{VPATH} to the value of another variable, for example
+@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do
+variable substitutions on the value of @code{VPATH}.
+
+@code{configure} substitutes in the correct value for @code{srcdir} when
+it produces @file{Makefile.in}.
+
+Do not use the @code{make} variable @code{$<}, which expands to the
+pathname of the file in the source directory (found with @code{VPATH}),
+except in implicit rules. (An implicit rule is one such as @samp{.c.o},
+which tells how to create a @file{.o} file from a @file{.c} file.) Some
+versions of @code{make} do not set @code{$<} in explicit rules; they
+expand it to an empty value.
+
+Instead, @file{Makefile} command lines should always refer to source
+files by prefixing them with @samp{$(srcdir)/}. For example:
+
+@example
+time.info: time.texinfo
+ $(MAKEINFO) $(srcdir)/time.texinfo
+@end example
+
+@node Automatic Remaking, , VPATH Substitutions, Makefiles
+@section Automatic Remaking
+
+You can put rules like the following in the top-level @file{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 @file{aclocal.m4} and those related to
+configuration header files. Omit from the @file{Makefile.in} rules any
+of these files that your package does not use.
+
+The @file{stamp-} files are necessary because the timestamps of
+@file{config.h.in} and @file{config.h} will not be changed if remaking
+them does not change their contents. This feature avoids unnecessary
+recompilation. You should include the file @file{stamp-h.in} your
+package's distribution, so @code{make} will consider @file{config.h.in}
+up to date.
+
+@example
+@group
+configure: configure.in aclocal.m4
+ cd $@{srcdir@} && autoconf
+
+# autoheader might not change config.h.in
+config.h.in: stamp-h.in
+stamp-h.in: configure.in aclocal.m4 acconfig.h config.h.top config.h.bot
+ cd $@{srcdir@} && autoheader
+ touch $@{srcdir@}/stamp-h.in
+
+# config.status might not change config.h
+config.h: stamp-h
+stamp-h: config.h.in config.status
+ ./config.status
+
+Makefile: Makefile.in config.status
+ ./config.status
-These macros provide ways for other macros to check whether various
-kinds of features are available and report the results. Within each
-section below, the macros are listed in alphabetical order.
+config.status: configure
+ ./config.status --recheck
+@end group
+@end example
+
+In addition, you should pass @samp{touch stamp-h} in the @var{extra-cmds}
+argument to @code{AC_OUTPUT}, so @file{config.status} will ensure that
+@file{config.h} is considered up to date. @xref{Output}, for more
+information about @code{AC_OUTPUT}.
+
+@xref{Invoking config.status}, for more information on handling
+configuration-related dependencies.
+
+@node Writing Tests, Writing Macros, Makefiles, Top
+@chapter Writing Tests
+
+If the existing feature tests don't do something you need, you have to
+write new ones. These macros are the building blocks. They provide
+ways for other macros to check whether various kinds of features are
+available and report the results.
+
+Here are some suggestions and some of the rationale behind why the
+existing tests are written the way they are. You can also learn a lot
+about how to write Autoconf tests by looking at the existing ones. If
+something goes wrong in one or more of the Autoconf tests, this
+information can help you understand why they work the way they do and
+the assumptions behind them, which might help you figure out how to best
+solve the problem.
@menu
-* C System Output:: Checking output of the C compiler system.
+* Checking for Symbols:: Finding whether a symbol is defined.
+* Test Programs:: Testing for run-time features.
+* Portable Shell:: Shell script portability pitfalls.
+* Testing Values and Files:: Checking strings and files.
+* Multiple Cases:: Tests for several possible values.
+* Defining Symbols:: Defining C preprocessor symbols.
* Setting Variables:: Setting shell and output variables.
* Printing Messages:: Notifying users of progress or problems.
* Language Choice:: Selecting which language to use for testing.
@end menu
-@node C System Output, Setting Variables, , Primitives
-@section Checking C Compiler System Output
+@node Checking for Symbols, Test Programs, , Writing Tests
+@section Checking for Symbols
These macros check the output of the C compiler system. They @emph{do
not} cache the results of their tests for future use (@pxref{Caching
features call these macros and do cache their results and print messages
about what they're checking for.
+Autoconf checks for many features by using these macros to examine or
+compile small test programs. To find out whether a library function is
+available, Autoconf tries to compile and link a small program that uses
+it. This is unlike Larry Wall's Metaconfig, which uses @code{nm} or
+@code{ar} on the C library to try to figure out which functions are
+available. Trying to link with the function is usually a more reliable
+and flexible approach because it avoids dealing with the variations in
+the options and output formats of @code{nm} and @code{ar} and in the
+location of the standard libraries. It also allows @code{configure} to
+check aspects of the function's runtime behavior if needed. On the
+other hand, it is sometimes slower than scanning the libraries.
+
@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]})
@maindex COMPILE_CHECK
This is an obsolete alias for @code{AC_TRY_LINK}, with the addition that it
@var{pattern}, execute shell commands @var{action-if-found}, otherwise
execute @var{action-if-not-found}.
+Use this macro instead of using @code{grep} directly on a header file,
+because on some systems it might be defined in another header file that
+the file you are checking @samp{#include}s.
+
This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending
on which language is current, @pxref{Language Choice}), if it hasn't
been called already.
correct. This is a problem that Autoconf does not currently address.
@end defmac
+@node Test Programs, Portable Shell, Checking for Symbols, Writing Tests
+@section Test Programs
+
+If you need to check for a condition other than whether some symbol
+exists on the system or has a certain value, then you can't use
+@code{AC_TRY_LINK} (@pxref{Checking for Symbols}). One alternative is
+to write a test program to determine the result, and compile and run it
+using @code{AC_TRY_RUN}.
+
@defmac AC_TRY_RUN (@var{program}, @var{action-if-true} @r{[}, @var{action-if-false} @r{[}, @var{action-if-cross-compiling}@r{]]})
@maindex TRY_RUN
@var{program} is the text of a C program, on which shell variable and
warning, though users will not be able to configure your package for
cross-compiling. A few of the macros distributed with Autoconf produce
this warning message.
-
-It is preferable to use @code{AC_TRY_LINK} instead of @code{AC_TRY_RUN},
-when possible. @xref{Test Programs}, for a fuller explanation.
@end defmac
-@node Setting Variables, Printing Messages, C System Output, Primitives
-@section Setting Variables
+@menu
+* Alternatives:: Approaches preferred over test programs.
+* Guidelines:: General rules for writing test programs.
+* Test Functions:: Avoiding pitfalls in test programs.
+@end menu
-These macros help other macros to define variables that are used in the
-@code{configure} shell script and substituted into output files.
+@node Alternatives, Guidelines, , Test Programs
+@subsection Alternatives to Test Programs
-@defmac AC_DEFINE (@var{variable} @r{[}, @var{value}@r{]})
-@maindex DEFINE
-Define C preprocessor variable @var{variable}. If @var{value} is given,
-set @var{variable} to that value (verbatim), otherwise set it to 1.
-@var{value} should not contain literal newlines, and if you are not
-using @code{AC_CONFIG_HEADER} it should not contain any @samp{#}
-characters, as @code{make} tends to eat them. To use a shell variable
-(which you need to do in order to define a value containing the
-@code{m4} quote characters @samp{[} or @samp{]}), use
-@code{AC_DEFINE_UNQUOTED} instead.
+Avoid running test programs if possible, because using them prevents
+people from configuring your package for cross-compiling. If you can,
+make the checks at run-time instead of at configure-time. You can check
+for things like the machine's endianness when your program initializes
+itself instead of when configuring it.
+
+If you still need to test for a run-time behavior while configuring, try
+to provide a default pessimistic value to use when cross-compiling
+makes run-time tests impossible. You do this by passing the optional
+last argument to @code{AC_TRY_RUN}. To configure for cross-compiling
+you can also choose a value for those parameters based on the canonical
+system name (@pxref{Manual Configuration}). Alternatively, set up a
+test results cache file with the correct values for the target system
+(@pxref{Caching Values}). But that is a quick-hack solution to the
+problem.
+
+To provide a default for calls of @code{AC_TRY_RUN} that are embedded in
+other macros, including a few of the ones that come with Autoconf, you
+can call @code{AC_C_CROSS} before running them. Then if the shell
+variable @code{cross_compiling} is set to @samp{yes}, use an alternate
+method to get the results instead of calling the macros.
+
+@node Guidelines, Test Functions, Alternatives, Test Programs
+@subsection Guidelines for Test Programs
+
+Test programs should not write anything to the standard output. They
+should return 0 if the test succeeds, nonzero otherwise, so that success
+can be distinguished easily from a core dump or other failure;
+segmentation violations and other failures produce a nonzero exit
+status. Test programs should @code{exit}, not @code{return}, from
+@code{main}, because on some systems (old Suns, at least) the argument
+to @code{return} in @code{main} is ignored.
+
+Test programs can use @code{#if} or @code{#ifdef} to check the values of
+preprocessor macros defined by tests that have already run. For
+example, if you call @code{AC_HEADER_STDC}, then later on in
+@file{configure.in} you can have a test program that includes an ANSI C
+header file conditionally:
+
+@example
+@group
+#if STDC_HEADERS
+# include <stdlib.h>
+#endif
+@end group
+@end example
+
+If a test program needs to use or create a data file, give it a name
+that starts with @file{conftest}, such as @file{conftestdata}. The
+@code{configure} script cleans up by running @samp{rm -rf conftest*}
+after running test programs and if the script is interrupted.
+
+@node Test Functions, , Guidelines, Test Programs
+@subsection Test Functions
+
+Functions that take arguments should have a prototype conditionalized
+for C++. In practice, test programs rarely need functions that take
+arguments.
+
+@example
+#ifdef __cplusplus
+foo(int i)
+#else
+foo(i) int i;
+#endif
+@end example
+
+Functions that test programs declare should also be conditionalized for
+C++, which requires @samp{extern "C"} prototypes. Make sure to not
+include any header files containing clashing prototypes.
+
+@example
+#ifdef __cplusplus
+extern "C" void *malloc(size_t);
+#else
+char *malloc();
+#endif
+@end example
+
+If a test program calls a function with invalid parameters (just to see
+whether it exists), organize the program to ensure that it never invokes
+that function. You can do this by calling it in another function that is
+never invoked. You can't do it by putting it after a call to
+@code{exit}, because GCC version 2 knows that @code{exit} never returns
+and optimizes out any code that follows it in the same block.
+
+If you include any header files, make sure to call the functions
+relevant to them with the correct number of arguments, even if they are
+just 0, to avoid compilation errors due to prototypes. GCC version 2
+has internal prototypes for several functions that it automatically
+inlines; for example, @code{memcpy}. To avoid errors when checking for
+them, either pass them the correct number of arguments or redeclare them
+with a different return type (such as @code{char}).
+
+@node Portable Shell, Testing Values and Files, Test Programs, Writing Tests
+@section Portable Shell Programming
+
+When writing your own checks, there are some shell script programming
+techniques you should avoid in order to make your code portable.
+The Bourne shell and upward-compatible shells like Bash and the Korn
+shell have evolved over the years, but to prevent trouble, do not take
+advantage of features that were added after UNIX version 7, circa 1977.
+You should not use shell functions, aliases, or other features that are
+not found in all Bourne-compatible shells; restrict yourself to the
+lowest common denominator. Even @code{unset} is not supported by all shells!
+
+The set of external programs you should run in a @code{configure} script
+is fairly small. @xref{Utilities in Makefiles, , Utilities in
+Makefiles, standards.info, GNU Coding Standards}, for the list. This
+restriction allows users to start out with a fairly small set of
+programs and build the rest, avoiding too many interdependencies between
+packages.
+
+Some of these external utilities have a portable subset of features, as
+well; for example, don't rely on @code{ln} having a @samp{-f} option or
+@code{cat} having any options. Don't use @samp{grep -s} to suppress
+output, because @samp{grep -s} on System V does not suppress output,
+only error messages. Instead, redirect the standard output and standard
+error (in case the file doesn't exist) of @code{grep} to
+@file{/dev/null}. Check the exit status of @code{grep} to determine
+whether it found a match.
+
+@node Testing Values and Files, Multiple Cases, Portable Shell, Writing Tests
+@section Testing Values and Files
+
+@code{configure} scripts need to test properties of many files and
+strings. Here are some portability problems to watch out for when doing
+those tests.
+
+The @code{test} program is the way to perform many file and string
+tests. If you need to make multiple checks using @code{test}, combine
+them with the shell operators @samp{&&} and @samp{||} instead of using
+the @code{test} operators @samp{-a} and @samp{-o}. On System V, the
+precedence of @samp{-a} and @samp{-o} is wrong relative to the unary
+operators; consequently, POSIX does not specify them, so using them is
+nonportable. If you combine @samp{&&} and @samp{||} in the same
+statement, keep in mind that they have equal precedence.
+
+To enable @code{configure} scripts to support cross-compilation, they
+shouldn't do anything that tests features of the host system instead of
+the target system. But occasionally you may find it necessary to check
+whether some arbitrary file exists. To do so, use @samp{test -f
+@var{filename}}. Do not use @samp{test -x}, because 4.3BSD does not
+have it. Use @samp{test -f} or @samp{test -r} instead.
+
+One subtly nonportable shell programming construction is
+@samp{@var{var}=$@{@var{var}:-@var{value}@}}. Old BSD shells, including
+the Ultrix @code{sh}, don't understand the colon, and complain and die.
+If you omit the colon, it works everywhere:
+@samp{@var{var}=$@{@var{var}-@var{value}@}}. Using the form without the
+colon has one small disadvantage. Users can not select a default value
+by giving a variable an empty value, e.g., @samp{CC= configure}.
+Instead, they must unset the variable, e.g., @samp{unset CC; configure}.
+If you want to distinguish an empty value from an unset one, you can do
+it in the following way. This example sets @code{CFLAGS} to @samp{-g}
+only if @code{CFLAGS} has not been set; if it has been set to an empty
+value, it is left unchanged:
+
+@example
+test "$@{CFLAGS+set@}" = set || CFLAGS='-g'
+@end example
+
+@node Multiple Cases, Defining Symbols, Testing Values and Files, Writing Tests
+@section Multiple Cases
+
+Some operations are accomplished in several possible ways, depending on
+the UNIX variant. Checking for them essentially requires a ``case
+statement''. Autoconf does not directly provide one; however, it is
+easy to simulate by using a shell variable to keep track of whether a
+way to perform the operation has been found yet.
+
+Here is an example excerpted from the @file{configure.in} for GNU
+@code{find}. It uses the shell variable @code{fstype} to keep track of
+whether the remaining cases need to be checked. There are several more
+cases which are not shown here but follow the same pattern.
+
+@example
+@group
+echo checking how to get filesystem type
+# SVR4.
+AC_TRY_CPP([#include <sys/statvfs.h>
+#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=1)
+if test -z "$fstype"; then
+# SVR3.
+AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=1)
+fi
+if test -z "$fstype"; then
+# AIX.
+AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=1)
+fi
+@end group
+@end example
+
+@node Defining Symbols, Setting Variables, Multiple Cases, Writing Tests
+@section Defining C Preprocessor Symbols
+
+The most common action to take in response to a feature test is to
+define a C preprocessor symbol indicating the results of the test.
+The two macros described below do that.
-By default, @code{AC_OUTPUT} substitutes the values defined by this
-macro as the variable @code{DEFS} in the file(s) that it generates
-(typically @file{Makefile}). Unlike in Autoconf version 1, there is no
-variable @code{DEFS} defined while @code{configure} is running;
-checking cache variable values is a cleaner way to get the effect of
-checking the value of @code{DEFS}.
+By default, @code{AC_OUTPUT} substitutes the symbols defined by these
+macros into the output variable @code{DEFS}, which contains an option
+@samp{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
+Autoconf version 1, there is no variable @code{DEFS} defined while
+@code{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:
+
+@example
+AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF))
+if test "$ac_cv_func_vprintf" != yes; then
+AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT))
+fi
+@end example
If @code{AC_CONFIG_HEADER} has been called, then instead of substituting
@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
@xref{Output}, for more information about this kind of output.
Due to the syntactical bizarreness of the Bourne shell, do not use
-semicolons to separate @code{AC_DEFINE} calls from other macro calls or
-shell code; that can cause syntax errors in the resulting
-@code{configure} script. Use either spaces or newlines. That is, do
-this:
+semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
+calls from other macro calls or shell code; that can cause syntax errors
+in the resulting @code{configure} script. Use either spaces or
+newlines. That is, do this:
@example
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf")
@example
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf")
@end example
+
+@defmac AC_DEFINE (@var{variable} @r{[}, @var{value}@r{]})
+@maindex DEFINE
+Define C preprocessor variable @var{variable}. If @var{value} is given,
+set @var{variable} to that value (verbatim), otherwise set it to 1.
+@var{value} should not contain literal newlines, and if you are not
+using @code{AC_CONFIG_HEADER} it should not contain any @samp{#}
+characters, as @code{make} tends to eat them. To use a shell variable
+(which you need to do in order to define a value containing the
+@code{m4} quote characters @samp{[} or @samp{]}), use
+@code{AC_DEFINE_UNQUOTED} instead.
@end defmac
@defmac AC_DEFINE_UNQUOTED (@var{variable} @r{[}, @var{value}@r{]})
@end example
@end defmac
+@node Setting Variables, Printing Messages, Defining Symbols, Writing Tests
+@section Setting Variables
+
+These macros help other macros to define variables that are used in the
+@code{configure} shell script and substituted into output files.
+
@defmac AC_SUBST (@var{variable})
@maindex SUBST
Substitute the variable @var{variable} when creating the output files
@end example
@end defmac
-@node Printing Messages, Language Choice, Setting Variables, Primitives
+@node Printing Messages, Language Choice, Setting Variables, Writing Tests
@section Printing Messages
@code{configure} scripts need to give users running them several kinds
is considered obsolete.
@end defmac
-@node Language Choice, , Printing Messages, Primitives
+@node Language Choice, , Printing Messages, Writing Tests
@section Language Choice
Packages that use both C and C++ need to test features of both
depending on which language is current.
@end defmac
-@node Writing Macros, Caching Values, Primitives, Top
+@node Writing Macros, Caching Values, Writing Tests, Top
@chapter Writing Macros
-If your package needs to test for some feature that none of the macros
-supplied with Autoconf handles, you'll need to write one or more new
-Autoconf macros. Here are some suggestions and some of the rationale
-behind why the existing macros are written the way they are. You can
-also learn a lot about how to write Autoconf macros by looking at the
-existing ones. If something goes wrong in one or more of the Autoconf
-tests, this information can help you understand why they work the way
-they do and the assumptions behind them, which might help you figure out
-how to best solve the problem.
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for doing so.
If you add macros that you think would be useful to other people, or
find problems with the distributed macros, please send electronic mail
* Macro Naming:: What to call your new macros.
* Quoting:: Protecting macros from unwanted expansion.
* Dependencies Between Macros:: What to do when macros depend on other macros.
-* Portable Shell:: Shell script portability pitfalls.
-* Checking for Files:: Finding whether a file exists.
-* Checking for Symbols:: Finding whether a symbol is defined.
-* Test Programs:: Writing programs to test for features.
-* Multiple Cases:: Tests for several possible values.
@end menu
@node Macro Format, Macro Naming, , Writing Macros
unexpanded macros. The @code{autoconf} program checks for this problem
by doing @samp{grep AC_ configure}.
-@node Dependencies Between Macros, Portable Shell, Quoting, Writing Macros
+@node Dependencies Between Macros, , Quoting, Writing Macros
@section Dependencies Between Macros
Some Autoconf macros depend on other macros having been called first in
@end example
@end defmac
-@node Portable Shell, Checking for Files, Dependencies Between Macros, Writing Macros
-@section Portable Shell Programming
+@node Caching Values, Manual Configuration, Writing Macros, Top
+@chapter Caching Values
-When writing your own checks, there are some shell script programming
-techniques you should avoid in order to make your code portable.
+To avoid checking for the same features repeatedly in various
+@code{configure} scripts (or repeated runs of one script),
+@code{configure} saves the results of many of its checks in a @dfn{cache
+file}. If, when a @code{configure} script runs, it finds a cache file,
+it reads from it the results from previous runs and avoids rerunning
+those checks. As a result, @code{configure} can run much faster than if
+it had to perform all of the checks every time.
-The Bourne shell and upward-compatible shells like Bash and the Korn
-shell have evolved over the years, but to prevent trouble, do not take
-advantage of features that were added after UNIX version 7, circa 1977.
-You should not use shell functions, aliases, or other features that are
-not found in all Bourne-compatible shells; restrict yourself to the
-lowest common denominator. Even @code{unset} is not found in all shells!
+@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
+@maindex CACHE_VAL
+Ensure that the results of the check identified by @var{cache-id} are
+available. If the results of the check were in the cache file that was
+read, and @code{configure} was not given the @samp{--quiet} or
+@samp{--silent} option, print a message saying that the result was
+cached; otherwise, run the shell commands @var{commands-to-set-it}.
+Those commands should have no side effects except for setting the
+variable @var{cache-id}. In particular, they should not call
+@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL}
+should do that, based on the cached value. Also, they should not print
+any messages, for example with @code{AC_MSG_CHECKING}; do that before
+calling @code{AC_CACHE_VAL}, so the messages are printed regardless of
+whether the results of the check are retrieved from the cache or
+determined by running the shell commands. If the shell commands are run
+to determine the value, the value will be saved in the cache file just
+before @code{configure} creates its output files. @xref{Cache
+Variables}, for how to choose the name of the @var{cache-id} variable.
+@end defmac
-One subtly nonportable shell programming construction is
-@samp{@var{var}=$@{@var{var}:-@var{value}@}}. Old BSD shells, including
-the Ultrix @code{sh}, don't understand the colon, and complain and die.
-If you omit the colon, it works everywhere:
-@samp{@var{var}=$@{@var{var}-@var{value}@}}. Using the form without the
-colon has one small disadvantage. Users can not select a default value
-by giving a variable an empty value, e.g., @samp{CC= configure}.
-Instead, they must unset the variable, e.g., @samp{unset CC; configure}.
-If you want to distinguish an empty value from an unset one, you can do
-it in the following way. This example sets @code{CFLAGS} to @samp{-g}
-only if @code{CFLAGS} has not been set; if it has been set to an empty
-value, it is left unchanged:
-
-@example
-test "$@{CFLAGS+set@}" = set || CFLAGS='-g'
-@end example
-
-The set of external programs you should run in a @code{configure} script
-is fairly small. @xref{Utilities in Makefiles, , Utilities in
-Makefiles, standards.info, GNU Coding Standards}, for the list. This
-restriction allows users to start out with a fairly small set of
-programs and build the rest, avoiding too many interdependencies between
-packages.
-
-Some of these external utilities have a portable subset of features, as
-well; for example, don't rely on @code{ln} having a @samp{-f} option or
-@code{cat} having any options.
-
-@node Checking for Files, Checking for Symbols, Portable Shell, Writing Macros
-@section Checking for Files
-
-To enable @code{configure} scripts to support cross-compilation, they
-shouldn't do anything that tests features of the host system instead of
-the target system. But occasionally you may find it necessary to check
-whether some arbitrary file exists.
-
-To do so, use @samp{test -f @var{filename}}. If you need to make
-multiple checks using @code{test}, combine them with the shell operators
-@samp{&&} and @samp{||} instead of using the @code{test} operators
-@samp{-a} and @samp{-o}. On System V, the precedence of @samp{-a} and
-@samp{-o} is wrong relative to the unary operators; consequently, POSIX
-does not specify them, so using them is nonportable. If you combine
-@samp{&&} and @samp{||} in the same statement, keep in mind that they
-have equal precedence.
-
-Do not use @samp{test -x}, because 4.3BSD does not have it. Use
-@samp{test -f} or @samp{test -r} instead.
-
-@node Checking for Symbols, Test Programs, Checking for Files, Writing Macros
-@section Checking for Symbols
-
-If you need to check whether a symbol is defined in a C header file, you
-can use @code{AC_EGREP_HEADER} if the symbol is not a C preprocessor
-macro (@pxref{C System Output}), or compile a small test program
-that includes the file and references the symbol (@pxref{Test
-Programs}). Don't directly @code{grep} for the symbol in the file,
-because on some systems it might be defined in another header file that
-the file you are checking @samp{#include}s.
-
-However, if you need to check for a particular UNIX variant which is
-distinguished by having certain text in a certain file, then use
-@code{grep} (or @code{egrep}). But don't use @samp{grep -s} to suppress
-output, because @samp{grep -s} on System V does not suppress output,
-only error messages. Instead, redirect the standard output and standard
-error (in case the file doesn't exist) of @code{grep} to
-@file{/dev/null}. Check the exit status of @code{grep} to determine
-whether it found a match.
-
-To check whether the Autoconf macros have already defined a certain C
-preprocessor symbol, test the value of the appropriate cache variable,
-as in this example:
-
-@example
-AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF))
-if test "$ac_cv_func_vprintf" != yes; then
-AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT))
-fi
-@end example
-
-@node Test Programs, Multiple Cases, Checking for Symbols, Writing Macros
-@section Test Programs
-
-Autoconf checks for many features by compiling small test programs. To
-find out whether a library function is available, Autoconf tries to
-compile a small program that uses it. This is unlike Larry Wall's
-Metaconfig, which uses @code{nm} or @code{ar} on the C library to try to
-figure out which functions are available. Trying to link with the
-function is usually a more reliable and flexible approach because it
-avoids dealing with the variations in the options and output formats of
-@code{nm} and @code{ar} and in the location of the standard libraries.
-It also allows @code{configure} to check aspects of the function's
-runtime behavior if needed. On the other hand, it is sometimes slower
-than scanning the libraries.
-
-If you need to check for a condition other than whether some symbol
-exists on the system or has a certain value, then you can't use
-@code{AC_TRY_LINK} (@pxref{C System Output}). You have to write a
-test program by hand. You can compile and run it using
-@code{AC_TRY_RUN} (@pxref{C System Output}).
-
-@menu
-* Alternatives:: Approaches preferred over test programs.
-* Guidelines:: General rules for writing test programs.
-* Test Functions:: Special ways to work around problems.
-@end menu
-
-@node Alternatives, Guidelines, , Test Programs
-@subsection Alternatives to Test Programs
-
-Avoid running test programs if possible, because using them prevents
-people from configuring your package for cross-compiling. If you can,
-make the checks at run-time instead of at configure-time. You can check
-for things like the machine's endianness when your program initializes
-itself instead of when configuring it.
-
-If you still need to test for a run-time behavior while configuring, try
-to provide a default pessimistic value to use when cross-compiling
-makes run-time tests impossible. You do this by passing the optional
-last argument to @code{AC_TRY_RUN}. To configure for cross-compiling
-you can also choose a value for those parameters based on the canonical
-system name (@pxref{Manual Configuration}). Alternatively, set up a
-test results cache file with the correct values for the target system
-(@pxref{Caching Values}). But that is a quick-hack solution to the
-problem.
-
-To provide a default for calls of @code{AC_TRY_RUN} that are embedded in
-other macros, including a few of the ones that come with Autoconf, you
-can call @code{AC_C_CROSS} before running them. Then if the shell
-variable @code{cross_compiling} is set to @samp{yes}, use an alternate
-method to get the results instead of calling the macros.
-
-@node Guidelines, Test Functions, Alternatives, Test Programs
-@subsection Guidelines for Test Programs
-
-Test programs should not write anything to the standard output. They
-should return 0 if the test succeeds, nonzero otherwise, so that success
-can be distinguished easily from a core dump or other failure;
-segmentation violations and other failures produce a nonzero exit
-status. Test programs should @code{exit}, not @code{return}, from
-@code{main}, because on some systems (old Suns, at least) the argument
-to @code{return} in @code{main} is ignored.
-
-Test programs can use @code{#if} or @code{#ifdef} to check the values of
-preprocessor macros defined by tests that have already run. For
-example, if you call @code{AC_HEADER_STDC}, then later on in
-@file{configure.in} you can have a test program that includes an ANSI C
-header file conditionally:
-
-@example
-@group
-#if STDC_HEADERS
-# include <stdlib.h>
-#endif
-@end group
-@end example
-
-If a test program needs to use or create a data file, give it a name
-that starts with @file{conftest}, such as @file{conftestdata}. The
-@code{configure} script cleans up by running @samp{rm -rf conftest*}
-after running test programs and if the script is interrupted.
-
-@node Test Functions, , Guidelines, Test Programs
-@subsection Test Functions
-
-Functions that take arguments should have a prototype conditionalized
-for C++. In practice, test programs rarely need functions that take
-arguments.
-
-@example
-#ifdef __cplusplus
-foo(int i)
-#else
-foo(i) int i;
-#endif
-@end example
-
-Functions that test programs declare should also be conditionalized for
-C++, which requires @samp{extern "C"} prototypes. Make sure to not
-include any header files containing clashing prototypes.
-
-@example
-#ifdef __cplusplus
-extern "C" void *malloc(size_t);
-#else
-char *malloc();
-#endif
-@end example
-
-If a test program calls a function with invalid parameters (just to see
-whether it exists), organize the program to ensure that it never invokes
-that function. You can do this by calling it in another function that is
-never invoked. You can't do it by putting it after a call to
-@code{exit}, because GCC version 2 knows that @code{exit} never returns
-and optimizes out any code that follows it in the same block.
-
-If you include any header files, make sure to call the functions
-relevant to them with the correct number of arguments, even if they are
-just 0, to avoid compilation errors due to prototypes. GCC version 2
-has internal prototypes for several functions that it automatically
-inlines; for example, @code{memcpy}. To avoid errors when checking for
-them, either pass them the correct number of arguments or redeclare them
-with a different return type (such as @code{char}).
-
-@node Multiple Cases, , Test Programs, Writing Macros
-@section Multiple Cases
-
-Some operations are accomplished in several possible ways, depending on
-the UNIX variant. Checking for them essentially requires a ``case
-statement''. Autoconf does not directly provide one; however, it is
-easy to simulate by using a shell variable to keep track of whether a
-way to perform the operation has been found yet.
-
-Here is an example excerpted from the @file{configure.in} for GNU
-@code{find}. It uses the shell variable @code{fstype} to keep track of
-whether the remaining cases need to be checked. There are several more
-cases which are not shown here but follow the same pattern.
-
-@example
-@group
-echo checking how to get filesystem type
-# SVR4.
-AC_TRY_CPP([#include <sys/statvfs.h>
-#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=1)
-if test -z "$fstype"; then
-# SVR3.
-AC_TRY_CPP([#include <sys/statfs.h>
-#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=1)
-fi
-if test -z "$fstype"; then
-# AIX.
-AC_TRY_CPP([#include <sys/statfs.h>
-#include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=1)
-fi
-@end group
-@end example
-
-@node Caching Values, Manual Configuration, Writing Macros, Top
-@chapter Caching Values
-
-To avoid checking for the same features repeatedly in various
-@code{configure} scripts (or repeated runs of one script),
-@code{configure} saves the results of many of its checks in a @dfn{cache
-file}. If, when a @code{configure} script runs, it finds a cache file,
-it reads from it the results from previous runs and avoids rerunning
-those checks. As a result, @code{configure} can run much faster than if
-it had to perform all of the checks every time.
-
-@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
-@maindex CACHE_VAL
-Ensure that the results of the check identified by @var{cache-id} are
-available. If the results of the check were in the cache file that was
-read, and @code{configure} was not given the @samp{--quiet} or
-@samp{--silent} option, print a message saying that the result was
-cached; otherwise, run the shell commands @var{commands-to-set-it}.
-Those commands should have no side effects except for setting the
-variable @var{cache-id}. In particular, they should not call
-@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL}
-should do that, based on the cached value. Also, they should not print
-any messages, for example with @code{AC_MSG_CHECKING}; do that before
-calling @code{AC_CACHE_VAL}, so the messages are printed regardless of
-whether the results of the check are retrieved from the cache or
-determined by running the shell commands. If the shell commands are run
-to determine the value, the value will be saved in the cache file just
-before @code{configure} creates its output files. @xref{Cache
-Variables}, for how to choose the name of the @var{cache-id} variable.
-@end defmac
-
-@menu
-* Cache Files:: Files @code{configure} uses for caching.
-* Cache Variables:: Shell variables used in caches.
-@end menu
+@menu
+* Cache Files:: Files @code{configure} uses for caching.
+* Cache Variables:: Shell variables used in caches.
+@end menu
@node Cache Files, Cache Variables, , Caching Values
@section Cache Files
Usually, their values will be boolean (@samp{yes} or @samp{no}) or the
names of files or functions; so this is not an important restriction.
-@node Manual Configuration, Makefiles, Caching Values, Top
+@node Manual Configuration, Invoking configure, Caching Values, Top
@chapter Manual Configuration
Some kinds of features can't be guessed automatically by running test
to @file{@var{srcdir}/config/aout.h}.
@end defmac
-@node Makefiles, Invoking configure, Manual Configuration, Top
-@chapter Makefiles
-
-Each subdirectory in a distribution should come with a file
-@file{Makefile.in}, from which @code{configure} will produce a
-@file{Makefile} in that directory. Most of the substitutions that
-@code{configure} does are simple: for each configuration variable that
-the package uses, it just replaces occurrences of
-@samp{@@@var{variable}@@} with the value that @code{configure} has
-determined for that variable. Any occurrences of
-@samp{@@@var{variable}@@} for variables that @code{configure} does not
-know about are passed through unchanged.
-
-There is no point in checking for the correct value to give a variable
-that is never used. Every variable that the @code{configure} script
-might set a value for should appear in a @samp{@@@var{variable}@@} reference
-in at least one @file{Makefile.in}.
-
-@xref{Makefile Conventions, , Makefile Conventions, standards.info, The
-GNU Coding Standards}, for more information on what to put in Makefiles.
-
-@menu
-* Predefined Variables:: Output variables that are always set.
-* VPATH Substitutions:: Compiling in a different directory.
-* Automatic Remaking:: Makefile rules for configuring.
-@end menu
-
-@node Predefined Variables, VPATH Substitutions, , Makefiles
-@section Predefined Variables
-
-Some output variables are predefined by the Autoconf macros.
-@code{AC_SUBST} is called for them automatically (@pxref{Setting
-Variables}), so in your @file{Makefile.in} files you can get their
-values by enclosing their names in @samp{@@} characters.
-@ifinfo
-@xref{Makefiles}, for more information on @samp{@@} substitutions.
-@end ifinfo
-The variables that are automatically defined by the Autoconf macros are
-listed here. Some of the Autoconf macros define additional variables,
-which are mentioned in the descriptions for those macros. @xref{Output
-Variable Index}, for a complete list of output variables.
-
-@defvar exec_prefix
-@ovindex exec_prefix
-The installation prefix for architecture-specific files.
-@end defvar
-
-@defvar prefix
-@ovindex prefix
-The installation prefix for architecture-independent files.
-@end defvar
-
-@defvar srcdir
-@ovindex srcdir
-The directory that contains the source code for that @file{Makefile}.
-@end defvar
-
-@defvar top_srcdir
-@ovindex top_srcdir
-The top-level source code directory for the package. In the top-level
-directory, this is the same as @code{srcdir}.
-@end defvar
-
-@defvar CFLAGS
-@ovindex CFLAGS
-Debugging and optimization options for the C compiler. If it is not set
-in the environment when @code{configure} runs, the default value is set
-when you call @code{AC_PROG_CC} (or empty if you don't). @code{configure}
-uses this variable when compiling programs to test for C features.
-@end defvar
-
-@defvar CPPFLAGS
-@ovindex CPPFLAGS
-Header file search directory (@samp{-I@var{dir}}) and any other
-miscellaneous options for the C preprocessor and compiler. If it is not
-set in the environment when @code{configure} runs, the default value is
-empty. @code{configure} uses this variable when compiling or
-preprocessing programs to test for C features.
-@end defvar
-
-@defvar CXXFLAGS
-@ovindex CXXFLAGS
-Debugging and optimization options for the C++ compiler. If it is not
-set in the environment when @code{configure} runs, the default value is
-set when you call @code{AC_PROG_CXX} (or empty if you don't).
-@code{configure} uses this variable when compiling programs to test for
-C++ features.
-@end defvar
-
-@defvar DEFS
-@ovindex DEFS
-@samp{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADER}
-is called, @code{configure} replaces @samp{@@DEFS@@} with
-@samp{-DHAVE_CONFIG_H} instead. This variable is not defined while
-@code{configure} is performing its tests, only when creating the output
-files. @xref{Setting Variables}, for more information.
-@end defvar
-
-@defvar LDFLAGS
-@ovindex LDFLAGS
-Stripping (@samp{-s}) and any other miscellaneous options for the
-linker. If it is not set in the environment when @code{configure} runs,
-the default value is empty. @code{configure} uses this variable when
-linking programs to test for C features.
-@end defvar
-
-@defvar LIBS
-@ovindex LIBS
-@samp{-l} and @samp{-L} options to pass to the linker.
-@end defvar
-
-@node VPATH Substitutions, Automatic Remaking, Predefined Variables, Makefiles
-@section @code{VPATH} Substitutions
-
-You might want to compile a software package in a different directory
-from the one that contains the source code. Doing this allows you to
-compile the package for several architectures simultaneously from the
-same copy of the source code and keep multiple sets of object files on
-disk.
-
-To support doing this, @code{make} uses the @code{VPATH} variable to
-find the files that are in the source directory. GNU @code{make} and
-most other recent @code{make} programs can do this. Older @code{make}
-programs do not support @code{VPATH}; when using them, the source code
-must be in the same directory as the object files.
-
-To support @code{VPATH}, each @file{Makefile.in} should contain two
-lines that look like:
-
-@example
-srcdir = @@srcdir@@
-VPATH = @@srcdir@@
-@end example
-
-Do not set @code{VPATH} to the value of another variable, for example
-@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do
-variable substitutions on the value of @code{VPATH}.
-
-@code{configure} substitutes in the correct value for @code{srcdir} when
-it produces @file{Makefile.in}.
-
-Do not use the @code{make} variable @code{$<}, which expands to the
-pathname of the file in the source directory (found with @code{VPATH}),
-except in implicit rules. (An implicit rule is one such as @samp{.c.o},
-which tells how to create a @file{.o} file from a @file{.c} file.) Some
-versions of @code{make} do not set @code{$<} in explicit rules; they
-expand it to an empty value.
-
-Instead, @file{Makefile} command lines should always refer to source
-files by prefixing them with @samp{$(srcdir)/}. For example:
-
-@example
-time.info: time.texinfo
- $(MAKEINFO) $(srcdir)/time.texinfo
-@end example
-
-@node Automatic Remaking, , VPATH Substitutions, Makefiles
-@section Automatic Remaking
-
-You can put rules like the following in the top-level @file{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 @file{aclocal.m4} and those related to
-configuration header files. Omit from the @file{Makefile.in} rules any
-of these files that your package does not use.
-
-The @file{stamp-} files are necessary because the timestamps of
-@file{config.h.in} and @file{config.h} will not be changed if remaking
-them does not change their contents. This feature avoids unnecessary
-recompilation. You should include the file @file{stamp-h.in} your
-package's distribution, so @code{make} will consider @file{config.h.in}
-up to date.
-
-@example
-@group
-configure: configure.in aclocal.m4
- cd $@{srcdir@} && autoconf
-
-# autoheader might not change config.h.in
-config.h.in: stamp-h.in
-stamp-h.in: configure.in aclocal.m4 acconfig.h config.h.top config.h.bot
- cd $@{srcdir@} && autoheader
- touch $@{srcdir@}/stamp-h.in
-
-# config.status might not change config.h
-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
-@end group
-@end example
-
-In addition, you should pass @samp{touch stamp-h} in the @var{extra-cmds}
-argument to @code{AC_OUTPUT}, so @file{config.status} will ensure that
-@file{config.h} is considered up to date. @xref{Output}, for more
-information about @code{AC_OUTPUT}.
-
-@xref{Invoking config.status}, for more information on handling
-configuration-related dependencies.
-
-@node Invoking configure, Invoking config.status, Makefiles, Top
+@node Invoking configure, Invoking config.status, Manual Configuration, Top
@chapter Running @code{configure} Scripts
A software package that uses a @code{configure} script
separately for each architecture.
@evindex CONFIG_SITE
-If the environment variable @code{CONFIG_SITE} is set and contains the
-name of a readable file, @code{configure} reads that file as a shell
-script. Otherwise, it reads the shell script
-@file{@var{prefix}/lib/config.site} if it exists, then
-@file{@var{exec_prefix}/lib/config.site} if it exists. Thus, settings in
-system dependent files override those in system independent ones in case
-of conflict. @code{configure} reads any cache file after it has read
-any site files. This way, the site file can define a default cache
-file, to be shared between all Autoconf-generated @code{configure}
-scripts run on that system.
+If the environment variable @code{CONFIG_SITE} is set, @code{configure}
+uses its value as the name of a shell script to read. Otherwise, it
+reads the shell script @file{@var{prefix}/lib/config.site} if it exists,
+then @file{@var{exec_prefix}/lib/config.site} if it exists. Thus,
+settings in system dependent files override those in system independent
+ones in case of conflict. @code{configure} reads any cache file after
+it has read any site files. This way, the site file can define a
+default cache file, to be shared between all Autoconf-generated
+@code{configure} scripts run on that system.
Site files can be arbitrary shell scripts, but only certain kinds of
code are really appropriate to be in them. Besides selecting a cache
# cache file for feature test results, architecture-specific.
test $cache_file = ./config.cache &&
cache_file=/usr/local/gnu/lib/config.cache
-# Also, if you give --prefix, you get --exec-prefix automatically.
+# Default --prefix and --exec-prefix.
+test $prefix = NONE && prefix=/usr/share/local/gnu
test $exec_prefix = NONE && exec_prefix=/usr/local/gnu
@end example
* Making configure Scripts:: How to organize and produce Autoconf scripts.
* Operation:: Controlling Autoconf operation.
* Existing Tests:: Macros that check for particular features.
-* Primitives:: Macros used to build other checks.
-* Writing Macros:: How to add your own macros to Autoconf.
+* Makefiles:: Information Autoconf uses in @file{Makefile}s.
+* Writing Tests:: How to write new feature checks.
+* Writing Macros:: Adding new macros to Autoconf.
* Caching Values:: Speeding up subsequent @code{configure} runs.
* Manual Configuration:: Selecting features that can't be guessed.
-* Makefiles:: Information Autoconf uses in @file{Makefile}s.
* Invoking configure:: How to use the Autoconf output.
* Invoking config.status:: Recreating a configuration.
* Site Default Values:: Providing local defaults for @code{configure}.
* Particular Functions:: Special handling to find certain functions.
* Generic Functions:: How to find other functions.
-Primitives For Building Tests
+Makefiles
+
+* Predefined Variables:: Output variables that are always set.
+* VPATH Substitutions:: Compiling in a different directory.
+* Automatic Remaking:: Makefile rules for configuring.
+
+Writing Tests
-* C System Output:: Checking output of the C compiler system.
+* Checking for Symbols:: Finding whether a symbol is defined.
+* Test Programs:: Testing for run-time features.
+* Portable Shell:: Shell script portability pitfalls.
+* Testing Values and Files:: Checking strings and files.
+* Multiple Cases:: Tests for several possible values.
+* Defining Symbols:: Defining C preprocessor symbols.
* Setting Variables:: Setting shell and output variables.
* Printing Messages:: Notifying users of progress or problems.
* Language Choice:: Selecting which language to use for testing.
+Test Programs
+
+* Alternatives:: Approaches preferred over test programs.
+* Guidelines:: General rules for writing test programs.
+* Test Functions:: Avoiding pitfalls in test programs.
+
Writing Macros
* Macro Format:: Basic format of an Autoconf macro.
* Macro Naming:: What to call your new macros.
* Quoting:: Protecting macros from unwanted expansion.
* Dependencies Between Macros:: What to do when macros depend on other macros.
-* Portable Shell:: Shell script portability pitfalls.
-* Checking for Files:: Finding whether a file exists.
-* Checking for Symbols:: Finding whether a symbol is defined.
-* Test Programs:: Writing programs to test for features.
-* Multiple Cases:: Tests for several possible values.
Dependencies Between Macros
* Suggested Ordering:: Warning about possible ordering problems.
* Obsolete Macros:: Warning about old ways of doing things.
-Test Programs
-
-* Alternatives:: Approaches preferred over test programs.
-* Guidelines:: General rules for writing test programs.
-* Test Functions:: Special ways to work around problems.
-
Caching Values
* Cache Files:: Files @code{configure} uses for caching.
* System Name Variables:: Variables containing the system type.
* Using System Type:: What to do with the system type.
-Makefiles
-
-* Predefined Variables:: Output variables that are always set.
-* VPATH Substitutions:: Compiling in a different directory.
-* Automatic Remaking:: Makefile rules for configuring.
-
Running @code{configure} Scripts
* Basic Installation:: Instructions for typical cases.
use. Autoconf macros already exist to check for many features; see
@ref{Existing Tests}, for their descriptions. For most other
features, you can use Autoconf template macros to produce custom checks;
-see @ref{Primitives}, for information about them. For especially
+see @ref{Writing Tests}, for information about them. For especially
tricky or specialized features, @file{configure.in} might need to
contain some hand-crafted shell commands. @xref{Writing Macros}, for
guidelines on writing tests from scratch.
@node Output, Package Options, Input, Operation
@section Controlling Autoconf Output
-The following macros control the kind of output that Autoconf produces.
+The following macros control which files Autoconf creates.
@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{})
@maindex CONFIG_HEADER
@end example
@end defmac
-@node Existing Tests, Primitives, Operation, Top
+@node Existing Tests, Makefiles, Operation, Top
@chapter Existing Tests
These macros test for particular system features that packages
might need or want to use. If you need to test for a kind of feature
that none of these macros check for, you can probably do it by calling
-primitive test macros with appropriate arguments (@pxref{Primitives}).
+primitive test macros with appropriate arguments (@pxref{Writing Tests}).
Some of these macros set variables whose values can be substituted into
output files. @xref{Setting Variables}, for details on how this is
@section Structures
The following macros check for certain structures or structure members.
-You can use @code{AC_TRY_LINK} (@pxref{C System Output}) to check
+You can use @code{AC_TRY_LINK} (@pxref{Checking for Symbols}) to check
structures not listed here.
@defmac AC_HEADER_STAT
@section Compiler Characteristics
The following macros check for C compiler or machine architecture
-features. You can use @code{AC_TRY_LINK} or @code{AC_TRY_RUN} (@pxref{C
-System Output}) to check for characteristics not listed here.
+features. You can use @code{AC_TRY_LINK} (@pxref{Checking for Symbols})
+or @code{AC_TRY_RUN} (@pxref{Test Programs}) to check for
+characteristics not listed here.
@defmac AC_C_BIGENDIAN
@maindex C_BIGENDIAN
variable @code{cross_compiling} to @samp{yes}, otherwise @samp{no}.
This information can be used by @code{AC_TRY_RUN} to determine whether
to take a default action instead of trying to run a test program
-(@pxref{C System Output}). For more information on dealing with
-cross-compiling, @xref{Alternatives}.
+For more information on dealing with test programs and
+cross-compiling, @xref{Test Programs}.
@end defmac
@defmac AC_C_INLINE
@code{AC_DIR_HEADER} if it has not been called already.
@end defmac
-@node Primitives, Writing Macros, Existing Tests, Top
-@chapter Primitives For Building Tests
+@node Makefiles, Writing Tests, Existing Tests, Top
+@chapter Makefiles
+
+Each subdirectory in a distribution should come with a file
+@file{Makefile.in}, from which @code{configure} will produce a
+@file{Makefile} in that directory. The substitutions that
+@code{configure} does are simple: for each output variable that the
+package sets, it replaces occurrences of @samp{@@@var{variable}@@} with
+the value that @code{configure} has determined for that variable. Any
+occurrences of @samp{@@@var{variable}@@} for variables that
+@code{configure} does not know about are passed through unchanged.
+
+Every variable that the @code{configure} script might set a value for
+should appear in a @samp{@@@var{variable}@@} reference in at least one
+@file{Makefile.in}. There is no point in checking for the correct value
+to give a variable that is never used.
+
+@xref{Makefile Conventions, , Makefile Conventions, standards.info, The
+GNU Coding Standards}, for more information on what to put in Makefiles.
+
+@menu
+* Predefined Variables:: Output variables that are always set.
+* VPATH Substitutions:: Compiling in a different directory.
+* Automatic Remaking:: Makefile rules for configuring.
+@end menu
+
+@node Predefined Variables, VPATH Substitutions, , Makefiles
+@section Predefined Variables
+
+Some output variables are predefined by the Autoconf macros.
+@code{AC_SUBST} is called for them automatically (@pxref{Setting
+Variables}), so in your @file{Makefile.in} files you can get their
+values by enclosing their names in @samp{@@} characters.
+@ifinfo
+@xref{Makefiles}, for more information on @samp{@@} substitutions.
+@end ifinfo
+The variables that are automatically defined by the Autoconf macros are
+listed here. Some of the Autoconf macros define additional variables,
+which are mentioned in the descriptions for those macros. @xref{Output
+Variable Index}, for a complete list of output variables.
+
+@defvar exec_prefix
+@ovindex exec_prefix
+The installation prefix for architecture-specific files.
+@end defvar
+
+@defvar prefix
+@ovindex prefix
+The installation prefix for architecture-independent files.
+@end defvar
+
+@defvar srcdir
+@ovindex srcdir
+The directory that contains the source code for that @file{Makefile}.
+@end defvar
+
+@defvar top_srcdir
+@ovindex top_srcdir
+The top-level source code directory for the package. In the top-level
+directory, this is the same as @code{srcdir}.
+@end defvar
+
+@defvar CFLAGS
+@ovindex CFLAGS
+Debugging and optimization options for the C compiler. If it is not set
+in the environment when @code{configure} runs, the default value is set
+when you call @code{AC_PROG_CC} (or empty if you don't). @code{configure}
+uses this variable when compiling programs to test for C features.
+@end defvar
+
+@defvar CPPFLAGS
+@ovindex CPPFLAGS
+Header file search directory (@samp{-I@var{dir}}) and any other
+miscellaneous options for the C preprocessor and compiler. If it is not
+set in the environment when @code{configure} runs, the default value is
+empty. @code{configure} uses this variable when compiling or
+preprocessing programs to test for C features.
+@end defvar
+
+@defvar CXXFLAGS
+@ovindex CXXFLAGS
+Debugging and optimization options for the C++ compiler. If it is not
+set in the environment when @code{configure} runs, the default value is
+set when you call @code{AC_PROG_CXX} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+C++ features.
+@end defvar
+
+@defvar DEFS
+@ovindex DEFS
+@samp{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADER}
+is called, @code{configure} replaces @samp{@@DEFS@@} with
+@samp{-DHAVE_CONFIG_H} instead. This variable is not defined while
+@code{configure} is performing its tests, only when creating the output
+files. @xref{Setting Variables}, for more information.
+@end defvar
+
+@defvar LDFLAGS
+@ovindex LDFLAGS
+Stripping (@samp{-s}) and any other miscellaneous options for the
+linker. If it is not set in the environment when @code{configure} runs,
+the default value is empty. @code{configure} uses this variable when
+linking programs to test for C features.
+@end defvar
+
+@defvar LIBS
+@ovindex LIBS
+@samp{-l} and @samp{-L} options to pass to the linker.
+@end defvar
+
+@node VPATH Substitutions, Automatic Remaking, Predefined Variables, Makefiles
+@section @code{VPATH} Substitutions
+
+You might want to compile a software package in a different directory
+from the one that contains the source code. Doing this allows you to
+compile the package for several architectures simultaneously from the
+same copy of the source code and keep multiple sets of object files on
+disk.
+
+To support doing this, @code{make} uses the @code{VPATH} variable to
+find the files that are in the source directory. GNU @code{make} and
+most other recent @code{make} programs can do this. Older @code{make}
+programs do not support @code{VPATH}; when using them, the source code
+must be in the same directory as the object files.
+
+To support @code{VPATH}, each @file{Makefile.in} should contain two
+lines that look like:
+
+@example
+srcdir = @@srcdir@@
+VPATH = @@srcdir@@
+@end example
+
+Do not set @code{VPATH} to the value of another variable, for example
+@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do
+variable substitutions on the value of @code{VPATH}.
+
+@code{configure} substitutes in the correct value for @code{srcdir} when
+it produces @file{Makefile.in}.
+
+Do not use the @code{make} variable @code{$<}, which expands to the
+pathname of the file in the source directory (found with @code{VPATH}),
+except in implicit rules. (An implicit rule is one such as @samp{.c.o},
+which tells how to create a @file{.o} file from a @file{.c} file.) Some
+versions of @code{make} do not set @code{$<} in explicit rules; they
+expand it to an empty value.
+
+Instead, @file{Makefile} command lines should always refer to source
+files by prefixing them with @samp{$(srcdir)/}. For example:
+
+@example
+time.info: time.texinfo
+ $(MAKEINFO) $(srcdir)/time.texinfo
+@end example
+
+@node Automatic Remaking, , VPATH Substitutions, Makefiles
+@section Automatic Remaking
+
+You can put rules like the following in the top-level @file{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 @file{aclocal.m4} and those related to
+configuration header files. Omit from the @file{Makefile.in} rules any
+of these files that your package does not use.
+
+The @file{stamp-} files are necessary because the timestamps of
+@file{config.h.in} and @file{config.h} will not be changed if remaking
+them does not change their contents. This feature avoids unnecessary
+recompilation. You should include the file @file{stamp-h.in} your
+package's distribution, so @code{make} will consider @file{config.h.in}
+up to date.
+
+@example
+@group
+configure: configure.in aclocal.m4
+ cd $@{srcdir@} && autoconf
+
+# autoheader might not change config.h.in
+config.h.in: stamp-h.in
+stamp-h.in: configure.in aclocal.m4 acconfig.h config.h.top config.h.bot
+ cd $@{srcdir@} && autoheader
+ touch $@{srcdir@}/stamp-h.in
+
+# config.status might not change config.h
+config.h: stamp-h
+stamp-h: config.h.in config.status
+ ./config.status
+
+Makefile: Makefile.in config.status
+ ./config.status
-These macros provide ways for other macros to check whether various
-kinds of features are available and report the results. Within each
-section below, the macros are listed in alphabetical order.
+config.status: configure
+ ./config.status --recheck
+@end group
+@end example
+
+In addition, you should pass @samp{touch stamp-h} in the @var{extra-cmds}
+argument to @code{AC_OUTPUT}, so @file{config.status} will ensure that
+@file{config.h} is considered up to date. @xref{Output}, for more
+information about @code{AC_OUTPUT}.
+
+@xref{Invoking config.status}, for more information on handling
+configuration-related dependencies.
+
+@node Writing Tests, Writing Macros, Makefiles, Top
+@chapter Writing Tests
+
+If the existing feature tests don't do something you need, you have to
+write new ones. These macros are the building blocks. They provide
+ways for other macros to check whether various kinds of features are
+available and report the results.
+
+Here are some suggestions and some of the rationale behind why the
+existing tests are written the way they are. You can also learn a lot
+about how to write Autoconf tests by looking at the existing ones. If
+something goes wrong in one or more of the Autoconf tests, this
+information can help you understand why they work the way they do and
+the assumptions behind them, which might help you figure out how to best
+solve the problem.
@menu
-* C System Output:: Checking output of the C compiler system.
+* Checking for Symbols:: Finding whether a symbol is defined.
+* Test Programs:: Testing for run-time features.
+* Portable Shell:: Shell script portability pitfalls.
+* Testing Values and Files:: Checking strings and files.
+* Multiple Cases:: Tests for several possible values.
+* Defining Symbols:: Defining C preprocessor symbols.
* Setting Variables:: Setting shell and output variables.
* Printing Messages:: Notifying users of progress or problems.
* Language Choice:: Selecting which language to use for testing.
@end menu
-@node C System Output, Setting Variables, , Primitives
-@section Checking C Compiler System Output
+@node Checking for Symbols, Test Programs, , Writing Tests
+@section Checking for Symbols
These macros check the output of the C compiler system. They @emph{do
not} cache the results of their tests for future use (@pxref{Caching
features call these macros and do cache their results and print messages
about what they're checking for.
+Autoconf checks for many features by using these macros to examine or
+compile small test programs. To find out whether a library function is
+available, Autoconf tries to compile and link a small program that uses
+it. This is unlike Larry Wall's Metaconfig, which uses @code{nm} or
+@code{ar} on the C library to try to figure out which functions are
+available. Trying to link with the function is usually a more reliable
+and flexible approach because it avoids dealing with the variations in
+the options and output formats of @code{nm} and @code{ar} and in the
+location of the standard libraries. It also allows @code{configure} to
+check aspects of the function's runtime behavior if needed. On the
+other hand, it is sometimes slower than scanning the libraries.
+
@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]})
@maindex COMPILE_CHECK
This is an obsolete alias for @code{AC_TRY_LINK}, with the addition that it
@var{pattern}, execute shell commands @var{action-if-found}, otherwise
execute @var{action-if-not-found}.
+Use this macro instead of using @code{grep} directly on a header file,
+because on some systems it might be defined in another header file that
+the file you are checking @samp{#include}s.
+
This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending
on which language is current, @pxref{Language Choice}), if it hasn't
been called already.
correct. This is a problem that Autoconf does not currently address.
@end defmac
+@node Test Programs, Portable Shell, Checking for Symbols, Writing Tests
+@section Test Programs
+
+If you need to check for a condition other than whether some symbol
+exists on the system or has a certain value, then you can't use
+@code{AC_TRY_LINK} (@pxref{Checking for Symbols}). One alternative is
+to write a test program to determine the result, and compile and run it
+using @code{AC_TRY_RUN}.
+
@defmac AC_TRY_RUN (@var{program}, @var{action-if-true} @r{[}, @var{action-if-false} @r{[}, @var{action-if-cross-compiling}@r{]]})
@maindex TRY_RUN
@var{program} is the text of a C program, on which shell variable and
warning, though users will not be able to configure your package for
cross-compiling. A few of the macros distributed with Autoconf produce
this warning message.
-
-It is preferable to use @code{AC_TRY_LINK} instead of @code{AC_TRY_RUN},
-when possible. @xref{Test Programs}, for a fuller explanation.
@end defmac
-@node Setting Variables, Printing Messages, C System Output, Primitives
-@section Setting Variables
+@menu
+* Alternatives:: Approaches preferred over test programs.
+* Guidelines:: General rules for writing test programs.
+* Test Functions:: Avoiding pitfalls in test programs.
+@end menu
-These macros help other macros to define variables that are used in the
-@code{configure} shell script and substituted into output files.
+@node Alternatives, Guidelines, , Test Programs
+@subsection Alternatives to Test Programs
-@defmac AC_DEFINE (@var{variable} @r{[}, @var{value}@r{]})
-@maindex DEFINE
-Define C preprocessor variable @var{variable}. If @var{value} is given,
-set @var{variable} to that value (verbatim), otherwise set it to 1.
-@var{value} should not contain literal newlines, and if you are not
-using @code{AC_CONFIG_HEADER} it should not contain any @samp{#}
-characters, as @code{make} tends to eat them. To use a shell variable
-(which you need to do in order to define a value containing the
-@code{m4} quote characters @samp{[} or @samp{]}), use
-@code{AC_DEFINE_UNQUOTED} instead.
+Avoid running test programs if possible, because using them prevents
+people from configuring your package for cross-compiling. If you can,
+make the checks at run-time instead of at configure-time. You can check
+for things like the machine's endianness when your program initializes
+itself instead of when configuring it.
+
+If you still need to test for a run-time behavior while configuring, try
+to provide a default pessimistic value to use when cross-compiling
+makes run-time tests impossible. You do this by passing the optional
+last argument to @code{AC_TRY_RUN}. To configure for cross-compiling
+you can also choose a value for those parameters based on the canonical
+system name (@pxref{Manual Configuration}). Alternatively, set up a
+test results cache file with the correct values for the target system
+(@pxref{Caching Values}). But that is a quick-hack solution to the
+problem.
+
+To provide a default for calls of @code{AC_TRY_RUN} that are embedded in
+other macros, including a few of the ones that come with Autoconf, you
+can call @code{AC_C_CROSS} before running them. Then if the shell
+variable @code{cross_compiling} is set to @samp{yes}, use an alternate
+method to get the results instead of calling the macros.
+
+@node Guidelines, Test Functions, Alternatives, Test Programs
+@subsection Guidelines for Test Programs
+
+Test programs should not write anything to the standard output. They
+should return 0 if the test succeeds, nonzero otherwise, so that success
+can be distinguished easily from a core dump or other failure;
+segmentation violations and other failures produce a nonzero exit
+status. Test programs should @code{exit}, not @code{return}, from
+@code{main}, because on some systems (old Suns, at least) the argument
+to @code{return} in @code{main} is ignored.
+
+Test programs can use @code{#if} or @code{#ifdef} to check the values of
+preprocessor macros defined by tests that have already run. For
+example, if you call @code{AC_HEADER_STDC}, then later on in
+@file{configure.in} you can have a test program that includes an ANSI C
+header file conditionally:
+
+@example
+@group
+#if STDC_HEADERS
+# include <stdlib.h>
+#endif
+@end group
+@end example
+
+If a test program needs to use or create a data file, give it a name
+that starts with @file{conftest}, such as @file{conftestdata}. The
+@code{configure} script cleans up by running @samp{rm -rf conftest*}
+after running test programs and if the script is interrupted.
+
+@node Test Functions, , Guidelines, Test Programs
+@subsection Test Functions
+
+Functions that take arguments should have a prototype conditionalized
+for C++. In practice, test programs rarely need functions that take
+arguments.
+
+@example
+#ifdef __cplusplus
+foo(int i)
+#else
+foo(i) int i;
+#endif
+@end example
+
+Functions that test programs declare should also be conditionalized for
+C++, which requires @samp{extern "C"} prototypes. Make sure to not
+include any header files containing clashing prototypes.
+
+@example
+#ifdef __cplusplus
+extern "C" void *malloc(size_t);
+#else
+char *malloc();
+#endif
+@end example
+
+If a test program calls a function with invalid parameters (just to see
+whether it exists), organize the program to ensure that it never invokes
+that function. You can do this by calling it in another function that is
+never invoked. You can't do it by putting it after a call to
+@code{exit}, because GCC version 2 knows that @code{exit} never returns
+and optimizes out any code that follows it in the same block.
+
+If you include any header files, make sure to call the functions
+relevant to them with the correct number of arguments, even if they are
+just 0, to avoid compilation errors due to prototypes. GCC version 2
+has internal prototypes for several functions that it automatically
+inlines; for example, @code{memcpy}. To avoid errors when checking for
+them, either pass them the correct number of arguments or redeclare them
+with a different return type (such as @code{char}).
+
+@node Portable Shell, Testing Values and Files, Test Programs, Writing Tests
+@section Portable Shell Programming
+
+When writing your own checks, there are some shell script programming
+techniques you should avoid in order to make your code portable.
+The Bourne shell and upward-compatible shells like Bash and the Korn
+shell have evolved over the years, but to prevent trouble, do not take
+advantage of features that were added after UNIX version 7, circa 1977.
+You should not use shell functions, aliases, or other features that are
+not found in all Bourne-compatible shells; restrict yourself to the
+lowest common denominator. Even @code{unset} is not supported by all shells!
+
+The set of external programs you should run in a @code{configure} script
+is fairly small. @xref{Utilities in Makefiles, , Utilities in
+Makefiles, standards.info, GNU Coding Standards}, for the list. This
+restriction allows users to start out with a fairly small set of
+programs and build the rest, avoiding too many interdependencies between
+packages.
+
+Some of these external utilities have a portable subset of features, as
+well; for example, don't rely on @code{ln} having a @samp{-f} option or
+@code{cat} having any options. Don't use @samp{grep -s} to suppress
+output, because @samp{grep -s} on System V does not suppress output,
+only error messages. Instead, redirect the standard output and standard
+error (in case the file doesn't exist) of @code{grep} to
+@file{/dev/null}. Check the exit status of @code{grep} to determine
+whether it found a match.
+
+@node Testing Values and Files, Multiple Cases, Portable Shell, Writing Tests
+@section Testing Values and Files
+
+@code{configure} scripts need to test properties of many files and
+strings. Here are some portability problems to watch out for when doing
+those tests.
+
+The @code{test} program is the way to perform many file and string
+tests. If you need to make multiple checks using @code{test}, combine
+them with the shell operators @samp{&&} and @samp{||} instead of using
+the @code{test} operators @samp{-a} and @samp{-o}. On System V, the
+precedence of @samp{-a} and @samp{-o} is wrong relative to the unary
+operators; consequently, POSIX does not specify them, so using them is
+nonportable. If you combine @samp{&&} and @samp{||} in the same
+statement, keep in mind that they have equal precedence.
+
+To enable @code{configure} scripts to support cross-compilation, they
+shouldn't do anything that tests features of the host system instead of
+the target system. But occasionally you may find it necessary to check
+whether some arbitrary file exists. To do so, use @samp{test -f
+@var{filename}}. Do not use @samp{test -x}, because 4.3BSD does not
+have it. Use @samp{test -f} or @samp{test -r} instead.
+
+One subtly nonportable shell programming construction is
+@samp{@var{var}=$@{@var{var}:-@var{value}@}}. Old BSD shells, including
+the Ultrix @code{sh}, don't understand the colon, and complain and die.
+If you omit the colon, it works everywhere:
+@samp{@var{var}=$@{@var{var}-@var{value}@}}. Using the form without the
+colon has one small disadvantage. Users can not select a default value
+by giving a variable an empty value, e.g., @samp{CC= configure}.
+Instead, they must unset the variable, e.g., @samp{unset CC; configure}.
+If you want to distinguish an empty value from an unset one, you can do
+it in the following way. This example sets @code{CFLAGS} to @samp{-g}
+only if @code{CFLAGS} has not been set; if it has been set to an empty
+value, it is left unchanged:
+
+@example
+test "$@{CFLAGS+set@}" = set || CFLAGS='-g'
+@end example
+
+@node Multiple Cases, Defining Symbols, Testing Values and Files, Writing Tests
+@section Multiple Cases
+
+Some operations are accomplished in several possible ways, depending on
+the UNIX variant. Checking for them essentially requires a ``case
+statement''. Autoconf does not directly provide one; however, it is
+easy to simulate by using a shell variable to keep track of whether a
+way to perform the operation has been found yet.
+
+Here is an example excerpted from the @file{configure.in} for GNU
+@code{find}. It uses the shell variable @code{fstype} to keep track of
+whether the remaining cases need to be checked. There are several more
+cases which are not shown here but follow the same pattern.
+
+@example
+@group
+echo checking how to get filesystem type
+# SVR4.
+AC_TRY_CPP([#include <sys/statvfs.h>
+#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=1)
+if test -z "$fstype"; then
+# SVR3.
+AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=1)
+fi
+if test -z "$fstype"; then
+# AIX.
+AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=1)
+fi
+@end group
+@end example
+
+@node Defining Symbols, Setting Variables, Multiple Cases, Writing Tests
+@section Defining C Preprocessor Symbols
+
+The most common action to take in response to a feature test is to
+define a C preprocessor symbol indicating the results of the test.
+The two macros described below do that.
-By default, @code{AC_OUTPUT} substitutes the values defined by this
-macro as the variable @code{DEFS} in the file(s) that it generates
-(typically @file{Makefile}). Unlike in Autoconf version 1, there is no
-variable @code{DEFS} defined while @code{configure} is running;
-checking cache variable values is a cleaner way to get the effect of
-checking the value of @code{DEFS}.
+By default, @code{AC_OUTPUT} substitutes the symbols defined by these
+macros into the output variable @code{DEFS}, which contains an option
+@samp{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
+Autoconf version 1, there is no variable @code{DEFS} defined while
+@code{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:
+
+@example
+AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF))
+if test "$ac_cv_func_vprintf" != yes; then
+AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT))
+fi
+@end example
If @code{AC_CONFIG_HEADER} has been called, then instead of substituting
@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
@xref{Output}, for more information about this kind of output.
Due to the syntactical bizarreness of the Bourne shell, do not use
-semicolons to separate @code{AC_DEFINE} calls from other macro calls or
-shell code; that can cause syntax errors in the resulting
-@code{configure} script. Use either spaces or newlines. That is, do
-this:
+semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
+calls from other macro calls or shell code; that can cause syntax errors
+in the resulting @code{configure} script. Use either spaces or
+newlines. That is, do this:
@example
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf")
@example
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf")
@end example
+
+@defmac AC_DEFINE (@var{variable} @r{[}, @var{value}@r{]})
+@maindex DEFINE
+Define C preprocessor variable @var{variable}. If @var{value} is given,
+set @var{variable} to that value (verbatim), otherwise set it to 1.
+@var{value} should not contain literal newlines, and if you are not
+using @code{AC_CONFIG_HEADER} it should not contain any @samp{#}
+characters, as @code{make} tends to eat them. To use a shell variable
+(which you need to do in order to define a value containing the
+@code{m4} quote characters @samp{[} or @samp{]}), use
+@code{AC_DEFINE_UNQUOTED} instead.
@end defmac
@defmac AC_DEFINE_UNQUOTED (@var{variable} @r{[}, @var{value}@r{]})
@end example
@end defmac
+@node Setting Variables, Printing Messages, Defining Symbols, Writing Tests
+@section Setting Variables
+
+These macros help other macros to define variables that are used in the
+@code{configure} shell script and substituted into output files.
+
@defmac AC_SUBST (@var{variable})
@maindex SUBST
Substitute the variable @var{variable} when creating the output files
@end example
@end defmac
-@node Printing Messages, Language Choice, Setting Variables, Primitives
+@node Printing Messages, Language Choice, Setting Variables, Writing Tests
@section Printing Messages
@code{configure} scripts need to give users running them several kinds
is considered obsolete.
@end defmac
-@node Language Choice, , Printing Messages, Primitives
+@node Language Choice, , Printing Messages, Writing Tests
@section Language Choice
Packages that use both C and C++ need to test features of both
depending on which language is current.
@end defmac
-@node Writing Macros, Caching Values, Primitives, Top
+@node Writing Macros, Caching Values, Writing Tests, Top
@chapter Writing Macros
-If your package needs to test for some feature that none of the macros
-supplied with Autoconf handles, you'll need to write one or more new
-Autoconf macros. Here are some suggestions and some of the rationale
-behind why the existing macros are written the way they are. You can
-also learn a lot about how to write Autoconf macros by looking at the
-existing ones. If something goes wrong in one or more of the Autoconf
-tests, this information can help you understand why they work the way
-they do and the assumptions behind them, which might help you figure out
-how to best solve the problem.
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for doing so.
If you add macros that you think would be useful to other people, or
find problems with the distributed macros, please send electronic mail
* Macro Naming:: What to call your new macros.
* Quoting:: Protecting macros from unwanted expansion.
* Dependencies Between Macros:: What to do when macros depend on other macros.
-* Portable Shell:: Shell script portability pitfalls.
-* Checking for Files:: Finding whether a file exists.
-* Checking for Symbols:: Finding whether a symbol is defined.
-* Test Programs:: Writing programs to test for features.
-* Multiple Cases:: Tests for several possible values.
@end menu
@node Macro Format, Macro Naming, , Writing Macros
unexpanded macros. The @code{autoconf} program checks for this problem
by doing @samp{grep AC_ configure}.
-@node Dependencies Between Macros, Portable Shell, Quoting, Writing Macros
+@node Dependencies Between Macros, , Quoting, Writing Macros
@section Dependencies Between Macros
Some Autoconf macros depend on other macros having been called first in
@end example
@end defmac
-@node Portable Shell, Checking for Files, Dependencies Between Macros, Writing Macros
-@section Portable Shell Programming
+@node Caching Values, Manual Configuration, Writing Macros, Top
+@chapter Caching Values
-When writing your own checks, there are some shell script programming
-techniques you should avoid in order to make your code portable.
+To avoid checking for the same features repeatedly in various
+@code{configure} scripts (or repeated runs of one script),
+@code{configure} saves the results of many of its checks in a @dfn{cache
+file}. If, when a @code{configure} script runs, it finds a cache file,
+it reads from it the results from previous runs and avoids rerunning
+those checks. As a result, @code{configure} can run much faster than if
+it had to perform all of the checks every time.
-The Bourne shell and upward-compatible shells like Bash and the Korn
-shell have evolved over the years, but to prevent trouble, do not take
-advantage of features that were added after UNIX version 7, circa 1977.
-You should not use shell functions, aliases, or other features that are
-not found in all Bourne-compatible shells; restrict yourself to the
-lowest common denominator. Even @code{unset} is not found in all shells!
+@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
+@maindex CACHE_VAL
+Ensure that the results of the check identified by @var{cache-id} are
+available. If the results of the check were in the cache file that was
+read, and @code{configure} was not given the @samp{--quiet} or
+@samp{--silent} option, print a message saying that the result was
+cached; otherwise, run the shell commands @var{commands-to-set-it}.
+Those commands should have no side effects except for setting the
+variable @var{cache-id}. In particular, they should not call
+@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL}
+should do that, based on the cached value. Also, they should not print
+any messages, for example with @code{AC_MSG_CHECKING}; do that before
+calling @code{AC_CACHE_VAL}, so the messages are printed regardless of
+whether the results of the check are retrieved from the cache or
+determined by running the shell commands. If the shell commands are run
+to determine the value, the value will be saved in the cache file just
+before @code{configure} creates its output files. @xref{Cache
+Variables}, for how to choose the name of the @var{cache-id} variable.
+@end defmac
-One subtly nonportable shell programming construction is
-@samp{@var{var}=$@{@var{var}:-@var{value}@}}. Old BSD shells, including
-the Ultrix @code{sh}, don't understand the colon, and complain and die.
-If you omit the colon, it works everywhere:
-@samp{@var{var}=$@{@var{var}-@var{value}@}}. Using the form without the
-colon has one small disadvantage. Users can not select a default value
-by giving a variable an empty value, e.g., @samp{CC= configure}.
-Instead, they must unset the variable, e.g., @samp{unset CC; configure}.
-If you want to distinguish an empty value from an unset one, you can do
-it in the following way. This example sets @code{CFLAGS} to @samp{-g}
-only if @code{CFLAGS} has not been set; if it has been set to an empty
-value, it is left unchanged:
-
-@example
-test "$@{CFLAGS+set@}" = set || CFLAGS='-g'
-@end example
-
-The set of external programs you should run in a @code{configure} script
-is fairly small. @xref{Utilities in Makefiles, , Utilities in
-Makefiles, standards.info, GNU Coding Standards}, for the list. This
-restriction allows users to start out with a fairly small set of
-programs and build the rest, avoiding too many interdependencies between
-packages.
-
-Some of these external utilities have a portable subset of features, as
-well; for example, don't rely on @code{ln} having a @samp{-f} option or
-@code{cat} having any options.
-
-@node Checking for Files, Checking for Symbols, Portable Shell, Writing Macros
-@section Checking for Files
-
-To enable @code{configure} scripts to support cross-compilation, they
-shouldn't do anything that tests features of the host system instead of
-the target system. But occasionally you may find it necessary to check
-whether some arbitrary file exists.
-
-To do so, use @samp{test -f @var{filename}}. If you need to make
-multiple checks using @code{test}, combine them with the shell operators
-@samp{&&} and @samp{||} instead of using the @code{test} operators
-@samp{-a} and @samp{-o}. On System V, the precedence of @samp{-a} and
-@samp{-o} is wrong relative to the unary operators; consequently, POSIX
-does not specify them, so using them is nonportable. If you combine
-@samp{&&} and @samp{||} in the same statement, keep in mind that they
-have equal precedence.
-
-Do not use @samp{test -x}, because 4.3BSD does not have it. Use
-@samp{test -f} or @samp{test -r} instead.
-
-@node Checking for Symbols, Test Programs, Checking for Files, Writing Macros
-@section Checking for Symbols
-
-If you need to check whether a symbol is defined in a C header file, you
-can use @code{AC_EGREP_HEADER} if the symbol is not a C preprocessor
-macro (@pxref{C System Output}), or compile a small test program
-that includes the file and references the symbol (@pxref{Test
-Programs}). Don't directly @code{grep} for the symbol in the file,
-because on some systems it might be defined in another header file that
-the file you are checking @samp{#include}s.
-
-However, if you need to check for a particular UNIX variant which is
-distinguished by having certain text in a certain file, then use
-@code{grep} (or @code{egrep}). But don't use @samp{grep -s} to suppress
-output, because @samp{grep -s} on System V does not suppress output,
-only error messages. Instead, redirect the standard output and standard
-error (in case the file doesn't exist) of @code{grep} to
-@file{/dev/null}. Check the exit status of @code{grep} to determine
-whether it found a match.
-
-To check whether the Autoconf macros have already defined a certain C
-preprocessor symbol, test the value of the appropriate cache variable,
-as in this example:
-
-@example
-AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF))
-if test "$ac_cv_func_vprintf" != yes; then
-AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT))
-fi
-@end example
-
-@node Test Programs, Multiple Cases, Checking for Symbols, Writing Macros
-@section Test Programs
-
-Autoconf checks for many features by compiling small test programs. To
-find out whether a library function is available, Autoconf tries to
-compile a small program that uses it. This is unlike Larry Wall's
-Metaconfig, which uses @code{nm} or @code{ar} on the C library to try to
-figure out which functions are available. Trying to link with the
-function is usually a more reliable and flexible approach because it
-avoids dealing with the variations in the options and output formats of
-@code{nm} and @code{ar} and in the location of the standard libraries.
-It also allows @code{configure} to check aspects of the function's
-runtime behavior if needed. On the other hand, it is sometimes slower
-than scanning the libraries.
-
-If you need to check for a condition other than whether some symbol
-exists on the system or has a certain value, then you can't use
-@code{AC_TRY_LINK} (@pxref{C System Output}). You have to write a
-test program by hand. You can compile and run it using
-@code{AC_TRY_RUN} (@pxref{C System Output}).
-
-@menu
-* Alternatives:: Approaches preferred over test programs.
-* Guidelines:: General rules for writing test programs.
-* Test Functions:: Special ways to work around problems.
-@end menu
-
-@node Alternatives, Guidelines, , Test Programs
-@subsection Alternatives to Test Programs
-
-Avoid running test programs if possible, because using them prevents
-people from configuring your package for cross-compiling. If you can,
-make the checks at run-time instead of at configure-time. You can check
-for things like the machine's endianness when your program initializes
-itself instead of when configuring it.
-
-If you still need to test for a run-time behavior while configuring, try
-to provide a default pessimistic value to use when cross-compiling
-makes run-time tests impossible. You do this by passing the optional
-last argument to @code{AC_TRY_RUN}. To configure for cross-compiling
-you can also choose a value for those parameters based on the canonical
-system name (@pxref{Manual Configuration}). Alternatively, set up a
-test results cache file with the correct values for the target system
-(@pxref{Caching Values}). But that is a quick-hack solution to the
-problem.
-
-To provide a default for calls of @code{AC_TRY_RUN} that are embedded in
-other macros, including a few of the ones that come with Autoconf, you
-can call @code{AC_C_CROSS} before running them. Then if the shell
-variable @code{cross_compiling} is set to @samp{yes}, use an alternate
-method to get the results instead of calling the macros.
-
-@node Guidelines, Test Functions, Alternatives, Test Programs
-@subsection Guidelines for Test Programs
-
-Test programs should not write anything to the standard output. They
-should return 0 if the test succeeds, nonzero otherwise, so that success
-can be distinguished easily from a core dump or other failure;
-segmentation violations and other failures produce a nonzero exit
-status. Test programs should @code{exit}, not @code{return}, from
-@code{main}, because on some systems (old Suns, at least) the argument
-to @code{return} in @code{main} is ignored.
-
-Test programs can use @code{#if} or @code{#ifdef} to check the values of
-preprocessor macros defined by tests that have already run. For
-example, if you call @code{AC_HEADER_STDC}, then later on in
-@file{configure.in} you can have a test program that includes an ANSI C
-header file conditionally:
-
-@example
-@group
-#if STDC_HEADERS
-# include <stdlib.h>
-#endif
-@end group
-@end example
-
-If a test program needs to use or create a data file, give it a name
-that starts with @file{conftest}, such as @file{conftestdata}. The
-@code{configure} script cleans up by running @samp{rm -rf conftest*}
-after running test programs and if the script is interrupted.
-
-@node Test Functions, , Guidelines, Test Programs
-@subsection Test Functions
-
-Functions that take arguments should have a prototype conditionalized
-for C++. In practice, test programs rarely need functions that take
-arguments.
-
-@example
-#ifdef __cplusplus
-foo(int i)
-#else
-foo(i) int i;
-#endif
-@end example
-
-Functions that test programs declare should also be conditionalized for
-C++, which requires @samp{extern "C"} prototypes. Make sure to not
-include any header files containing clashing prototypes.
-
-@example
-#ifdef __cplusplus
-extern "C" void *malloc(size_t);
-#else
-char *malloc();
-#endif
-@end example
-
-If a test program calls a function with invalid parameters (just to see
-whether it exists), organize the program to ensure that it never invokes
-that function. You can do this by calling it in another function that is
-never invoked. You can't do it by putting it after a call to
-@code{exit}, because GCC version 2 knows that @code{exit} never returns
-and optimizes out any code that follows it in the same block.
-
-If you include any header files, make sure to call the functions
-relevant to them with the correct number of arguments, even if they are
-just 0, to avoid compilation errors due to prototypes. GCC version 2
-has internal prototypes for several functions that it automatically
-inlines; for example, @code{memcpy}. To avoid errors when checking for
-them, either pass them the correct number of arguments or redeclare them
-with a different return type (such as @code{char}).
-
-@node Multiple Cases, , Test Programs, Writing Macros
-@section Multiple Cases
-
-Some operations are accomplished in several possible ways, depending on
-the UNIX variant. Checking for them essentially requires a ``case
-statement''. Autoconf does not directly provide one; however, it is
-easy to simulate by using a shell variable to keep track of whether a
-way to perform the operation has been found yet.
-
-Here is an example excerpted from the @file{configure.in} for GNU
-@code{find}. It uses the shell variable @code{fstype} to keep track of
-whether the remaining cases need to be checked. There are several more
-cases which are not shown here but follow the same pattern.
-
-@example
-@group
-echo checking how to get filesystem type
-# SVR4.
-AC_TRY_CPP([#include <sys/statvfs.h>
-#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=1)
-if test -z "$fstype"; then
-# SVR3.
-AC_TRY_CPP([#include <sys/statfs.h>
-#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=1)
-fi
-if test -z "$fstype"; then
-# AIX.
-AC_TRY_CPP([#include <sys/statfs.h>
-#include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=1)
-fi
-@end group
-@end example
-
-@node Caching Values, Manual Configuration, Writing Macros, Top
-@chapter Caching Values
-
-To avoid checking for the same features repeatedly in various
-@code{configure} scripts (or repeated runs of one script),
-@code{configure} saves the results of many of its checks in a @dfn{cache
-file}. If, when a @code{configure} script runs, it finds a cache file,
-it reads from it the results from previous runs and avoids rerunning
-those checks. As a result, @code{configure} can run much faster than if
-it had to perform all of the checks every time.
-
-@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
-@maindex CACHE_VAL
-Ensure that the results of the check identified by @var{cache-id} are
-available. If the results of the check were in the cache file that was
-read, and @code{configure} was not given the @samp{--quiet} or
-@samp{--silent} option, print a message saying that the result was
-cached; otherwise, run the shell commands @var{commands-to-set-it}.
-Those commands should have no side effects except for setting the
-variable @var{cache-id}. In particular, they should not call
-@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL}
-should do that, based on the cached value. Also, they should not print
-any messages, for example with @code{AC_MSG_CHECKING}; do that before
-calling @code{AC_CACHE_VAL}, so the messages are printed regardless of
-whether the results of the check are retrieved from the cache or
-determined by running the shell commands. If the shell commands are run
-to determine the value, the value will be saved in the cache file just
-before @code{configure} creates its output files. @xref{Cache
-Variables}, for how to choose the name of the @var{cache-id} variable.
-@end defmac
-
-@menu
-* Cache Files:: Files @code{configure} uses for caching.
-* Cache Variables:: Shell variables used in caches.
-@end menu
+@menu
+* Cache Files:: Files @code{configure} uses for caching.
+* Cache Variables:: Shell variables used in caches.
+@end menu
@node Cache Files, Cache Variables, , Caching Values
@section Cache Files
Usually, their values will be boolean (@samp{yes} or @samp{no}) or the
names of files or functions; so this is not an important restriction.
-@node Manual Configuration, Makefiles, Caching Values, Top
+@node Manual Configuration, Invoking configure, Caching Values, Top
@chapter Manual Configuration
Some kinds of features can't be guessed automatically by running test
to @file{@var{srcdir}/config/aout.h}.
@end defmac
-@node Makefiles, Invoking configure, Manual Configuration, Top
-@chapter Makefiles
-
-Each subdirectory in a distribution should come with a file
-@file{Makefile.in}, from which @code{configure} will produce a
-@file{Makefile} in that directory. Most of the substitutions that
-@code{configure} does are simple: for each configuration variable that
-the package uses, it just replaces occurrences of
-@samp{@@@var{variable}@@} with the value that @code{configure} has
-determined for that variable. Any occurrences of
-@samp{@@@var{variable}@@} for variables that @code{configure} does not
-know about are passed through unchanged.
-
-There is no point in checking for the correct value to give a variable
-that is never used. Every variable that the @code{configure} script
-might set a value for should appear in a @samp{@@@var{variable}@@} reference
-in at least one @file{Makefile.in}.
-
-@xref{Makefile Conventions, , Makefile Conventions, standards.info, The
-GNU Coding Standards}, for more information on what to put in Makefiles.
-
-@menu
-* Predefined Variables:: Output variables that are always set.
-* VPATH Substitutions:: Compiling in a different directory.
-* Automatic Remaking:: Makefile rules for configuring.
-@end menu
-
-@node Predefined Variables, VPATH Substitutions, , Makefiles
-@section Predefined Variables
-
-Some output variables are predefined by the Autoconf macros.
-@code{AC_SUBST} is called for them automatically (@pxref{Setting
-Variables}), so in your @file{Makefile.in} files you can get their
-values by enclosing their names in @samp{@@} characters.
-@ifinfo
-@xref{Makefiles}, for more information on @samp{@@} substitutions.
-@end ifinfo
-The variables that are automatically defined by the Autoconf macros are
-listed here. Some of the Autoconf macros define additional variables,
-which are mentioned in the descriptions for those macros. @xref{Output
-Variable Index}, for a complete list of output variables.
-
-@defvar exec_prefix
-@ovindex exec_prefix
-The installation prefix for architecture-specific files.
-@end defvar
-
-@defvar prefix
-@ovindex prefix
-The installation prefix for architecture-independent files.
-@end defvar
-
-@defvar srcdir
-@ovindex srcdir
-The directory that contains the source code for that @file{Makefile}.
-@end defvar
-
-@defvar top_srcdir
-@ovindex top_srcdir
-The top-level source code directory for the package. In the top-level
-directory, this is the same as @code{srcdir}.
-@end defvar
-
-@defvar CFLAGS
-@ovindex CFLAGS
-Debugging and optimization options for the C compiler. If it is not set
-in the environment when @code{configure} runs, the default value is set
-when you call @code{AC_PROG_CC} (or empty if you don't). @code{configure}
-uses this variable when compiling programs to test for C features.
-@end defvar
-
-@defvar CPPFLAGS
-@ovindex CPPFLAGS
-Header file search directory (@samp{-I@var{dir}}) and any other
-miscellaneous options for the C preprocessor and compiler. If it is not
-set in the environment when @code{configure} runs, the default value is
-empty. @code{configure} uses this variable when compiling or
-preprocessing programs to test for C features.
-@end defvar
-
-@defvar CXXFLAGS
-@ovindex CXXFLAGS
-Debugging and optimization options for the C++ compiler. If it is not
-set in the environment when @code{configure} runs, the default value is
-set when you call @code{AC_PROG_CXX} (or empty if you don't).
-@code{configure} uses this variable when compiling programs to test for
-C++ features.
-@end defvar
-
-@defvar DEFS
-@ovindex DEFS
-@samp{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADER}
-is called, @code{configure} replaces @samp{@@DEFS@@} with
-@samp{-DHAVE_CONFIG_H} instead. This variable is not defined while
-@code{configure} is performing its tests, only when creating the output
-files. @xref{Setting Variables}, for more information.
-@end defvar
-
-@defvar LDFLAGS
-@ovindex LDFLAGS
-Stripping (@samp{-s}) and any other miscellaneous options for the
-linker. If it is not set in the environment when @code{configure} runs,
-the default value is empty. @code{configure} uses this variable when
-linking programs to test for C features.
-@end defvar
-
-@defvar LIBS
-@ovindex LIBS
-@samp{-l} and @samp{-L} options to pass to the linker.
-@end defvar
-
-@node VPATH Substitutions, Automatic Remaking, Predefined Variables, Makefiles
-@section @code{VPATH} Substitutions
-
-You might want to compile a software package in a different directory
-from the one that contains the source code. Doing this allows you to
-compile the package for several architectures simultaneously from the
-same copy of the source code and keep multiple sets of object files on
-disk.
-
-To support doing this, @code{make} uses the @code{VPATH} variable to
-find the files that are in the source directory. GNU @code{make} and
-most other recent @code{make} programs can do this. Older @code{make}
-programs do not support @code{VPATH}; when using them, the source code
-must be in the same directory as the object files.
-
-To support @code{VPATH}, each @file{Makefile.in} should contain two
-lines that look like:
-
-@example
-srcdir = @@srcdir@@
-VPATH = @@srcdir@@
-@end example
-
-Do not set @code{VPATH} to the value of another variable, for example
-@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do
-variable substitutions on the value of @code{VPATH}.
-
-@code{configure} substitutes in the correct value for @code{srcdir} when
-it produces @file{Makefile.in}.
-
-Do not use the @code{make} variable @code{$<}, which expands to the
-pathname of the file in the source directory (found with @code{VPATH}),
-except in implicit rules. (An implicit rule is one such as @samp{.c.o},
-which tells how to create a @file{.o} file from a @file{.c} file.) Some
-versions of @code{make} do not set @code{$<} in explicit rules; they
-expand it to an empty value.
-
-Instead, @file{Makefile} command lines should always refer to source
-files by prefixing them with @samp{$(srcdir)/}. For example:
-
-@example
-time.info: time.texinfo
- $(MAKEINFO) $(srcdir)/time.texinfo
-@end example
-
-@node Automatic Remaking, , VPATH Substitutions, Makefiles
-@section Automatic Remaking
-
-You can put rules like the following in the top-level @file{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 @file{aclocal.m4} and those related to
-configuration header files. Omit from the @file{Makefile.in} rules any
-of these files that your package does not use.
-
-The @file{stamp-} files are necessary because the timestamps of
-@file{config.h.in} and @file{config.h} will not be changed if remaking
-them does not change their contents. This feature avoids unnecessary
-recompilation. You should include the file @file{stamp-h.in} your
-package's distribution, so @code{make} will consider @file{config.h.in}
-up to date.
-
-@example
-@group
-configure: configure.in aclocal.m4
- cd $@{srcdir@} && autoconf
-
-# autoheader might not change config.h.in
-config.h.in: stamp-h.in
-stamp-h.in: configure.in aclocal.m4 acconfig.h config.h.top config.h.bot
- cd $@{srcdir@} && autoheader
- touch $@{srcdir@}/stamp-h.in
-
-# config.status might not change config.h
-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
-@end group
-@end example
-
-In addition, you should pass @samp{touch stamp-h} in the @var{extra-cmds}
-argument to @code{AC_OUTPUT}, so @file{config.status} will ensure that
-@file{config.h} is considered up to date. @xref{Output}, for more
-information about @code{AC_OUTPUT}.
-
-@xref{Invoking config.status}, for more information on handling
-configuration-related dependencies.
-
-@node Invoking configure, Invoking config.status, Makefiles, Top
+@node Invoking configure, Invoking config.status, Manual Configuration, Top
@chapter Running @code{configure} Scripts
A software package that uses a @code{configure} script
separately for each architecture.
@evindex CONFIG_SITE
-If the environment variable @code{CONFIG_SITE} is set and contains the
-name of a readable file, @code{configure} reads that file as a shell
-script. Otherwise, it reads the shell script
-@file{@var{prefix}/lib/config.site} if it exists, then
-@file{@var{exec_prefix}/lib/config.site} if it exists. Thus, settings in
-system dependent files override those in system independent ones in case
-of conflict. @code{configure} reads any cache file after it has read
-any site files. This way, the site file can define a default cache
-file, to be shared between all Autoconf-generated @code{configure}
-scripts run on that system.
+If the environment variable @code{CONFIG_SITE} is set, @code{configure}
+uses its value as the name of a shell script to read. Otherwise, it
+reads the shell script @file{@var{prefix}/lib/config.site} if it exists,
+then @file{@var{exec_prefix}/lib/config.site} if it exists. Thus,
+settings in system dependent files override those in system independent
+ones in case of conflict. @code{configure} reads any cache file after
+it has read any site files. This way, the site file can define a
+default cache file, to be shared between all Autoconf-generated
+@code{configure} scripts run on that system.
Site files can be arbitrary shell scripts, but only certain kinds of
code are really appropriate to be in them. Besides selecting a cache
# cache file for feature test results, architecture-specific.
test $cache_file = ./config.cache &&
cache_file=/usr/local/gnu/lib/config.cache
-# Also, if you give --prefix, you get --exec-prefix automatically.
+# Default --prefix and --exec-prefix.
+test $prefix = NONE && prefix=/usr/share/local/gnu
test $exec_prefix = NONE && exec_prefix=/usr/local/gnu
@end example
projects / thirdparty / autoconf.git / commitdiff
