mirror of
git://git.sv.gnu.org/autoconf
synced 2024-12-09 02:10:22 +08:00
4625 lines
180 KiB
Plaintext
4625 lines
180 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename autoconf.info
|
|
@settitle Autoconf
|
|
@c For double-sided printing, uncomment:
|
|
@c @setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
@set EDITION 1.112
|
|
@set VERSION 1.112
|
|
@set UPDATED September 1994
|
|
|
|
@iftex
|
|
@finalout
|
|
@end iftex
|
|
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* Autoconf: (autoconf). Create source code configuration scripts.
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
|
|
This file documents the GNU Autoconf package for creating scripts to
|
|
configure source code packages using templates and an @code{m4} macro
|
|
package.
|
|
|
|
Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the entire
|
|
resulting derived work is distributed under the terms of a permission
|
|
notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation approved
|
|
by the Foundation.
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title Autoconf
|
|
@subtitle Generating Automatic Configuration Scripts
|
|
@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION}
|
|
@subtitle @value{UPDATED}
|
|
@author by David MacKenzie
|
|
@c I think I've rewritten all of Noah and Roland's contributions by now.
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the entire
|
|
resulting derived work is distributed under the terms of a permission
|
|
notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation approved
|
|
by the Foundation.
|
|
@end titlepage
|
|
|
|
@c Define an environment variable index.
|
|
@defcodeindex ev
|
|
@c Define an output variable index.
|
|
@defcodeindex ov
|
|
@c Define a CPP variable index.
|
|
@defcodeindex cv
|
|
@c Define a macro index that @@defmac doesn't write to.
|
|
@defcodeindex ma
|
|
|
|
@node Top, Introduction, , (dir)
|
|
@comment node-name, next, previous, up
|
|
|
|
@ifinfo
|
|
This file documents the GNU Autoconf package for creating scripts to
|
|
configure source code packages using templates and an @code{m4} macro
|
|
package. This is edition @value{EDITION}, for Autoconf version @value{VERSION}.
|
|
|
|
@end ifinfo
|
|
|
|
@c The master menu, created with texinfo-master-menu, goes here.
|
|
|
|
@menu
|
|
* Introduction:: Autoconf's purpose, strengths, and weaknesses.
|
|
* 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.
|
|
* 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}.
|
|
* Concerns:: Concerns about Autoconf, with answers.
|
|
* Upgrading:: Tips for upgrading from version 1.
|
|
* History:: History of Autoconf.
|
|
* Old Macro Names:: Backward compatibility macros.
|
|
* Environment Variable Index:: Index of environment variables used.
|
|
* Output Variable Index:: Index of variables set in output files.
|
|
* Preprocessor Symbol Index:: Index of C preprocessor symbols defined.
|
|
* Macro Index:: Index of Autoconf macros.
|
|
|
|
--- The Detailed Node Listing ---
|
|
|
|
Making @code{configure} Scripts
|
|
|
|
* Writing configure.in:: What to put in an Autoconf input file.
|
|
* Invoking autoconf:: How to create configuration scripts.
|
|
* Invoking autoheader:: How to create configuration header files.
|
|
* Invoking autoscan:: Semi-automatic @file{configure.in} writing.
|
|
* Invoking ifnames:: Listing the conditionals in source code.
|
|
* Invoking autoreconf:: Remaking multiple @code{configure} scripts.
|
|
* Invoking autoupdate:: Replacing old macro names in @code{configure.in}.
|
|
|
|
Controlling Autoconf Operation
|
|
|
|
* Input:: Where Autoconf should find files.
|
|
* Output:: Controlling Autoconf output files.
|
|
* Package Options:: Selecting optional features.
|
|
* Transforming Names:: Changing program names when installing.
|
|
* Versions:: Version numbers in producing @code{configure}.
|
|
|
|
Existing Tests
|
|
|
|
* Alternative Programs:: Selecting between alternative programs.
|
|
* Libraries:: Library archives that might be missing.
|
|
* Header Files:: Header files that might be missing.
|
|
* Typedefs:: @code{typedef}s that might be missing.
|
|
* Library Functions:: C library functions that might be missing.
|
|
* Structures:: Structures or members that might be missing.
|
|
* Compiler Characteristics:: C compiler or machine architecture features.
|
|
* System Services:: Operating system services.
|
|
* UNIX Variants:: Special cases for specific UNIX variants.
|
|
|
|
Alternative Programs
|
|
|
|
* Particular Programs:: Special handling to find certain programs.
|
|
* Generic Programs:: How to find other programs.
|
|
|
|
Header Files
|
|
|
|
* Particular Headers:: Special handling to find certain headers.
|
|
* Generic Headers:: How to find other headers.
|
|
|
|
Typedefs
|
|
|
|
* Particular Types:: Special handling to find certain types.
|
|
* Generic Types:: How to find other types.
|
|
|
|
Library Functions
|
|
|
|
* Particular Functions:: Special handling to find certain functions.
|
|
* Generic Functions:: How to find other functions.
|
|
|
|
Primitives For Building Tests
|
|
|
|
* C System Output:: Checking output of the C compiler system.
|
|
* Setting Variables:: Setting shell and output variables.
|
|
* Printing Messages:: Notifying users of progress or problems.
|
|
* Language Choice:: Selecting which language to use for testing.
|
|
|
|
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
|
|
|
|
* Prerequisite Macros:: Ensuring required information.
|
|
* 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.
|
|
* Cache Variables:: Shell variables used in caches.
|
|
|
|
Manual Configuration
|
|
|
|
* Specifying Names:: Specifying the system type.
|
|
* Canonicalizing:: Getting the canonical system type.
|
|
* 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.
|
|
* Compilers and Options:: Selecting compilers and optimization.
|
|
* Build Directory:: Configuring in a different directory.
|
|
* Installation Names:: Installing in different directories.
|
|
* System Type:: Specifying the system type.
|
|
* Optional Features:: Selecting optional features.
|
|
|
|
Concerns About Autoconf
|
|
|
|
* Copyright:: Legal restrictions on Autoconf output.
|
|
* Why GNU m4:: Why not use the standard @code{m4}?
|
|
* Bootstrapping:: Autoconf and GNU @code{m4} require each other?
|
|
* Policy Decisions:: Configuring site policy.
|
|
|
|
Upgrading From Version 1
|
|
|
|
* Changed File Names:: Files you might rename.
|
|
* Changed Makefiles:: New things to put in @file{Makefile.in}.
|
|
* Changed Macros:: Macro calls you might replace.
|
|
* Changed Results:: Changes in how to check test results.
|
|
* Changed Macro Writing:: Better ways to write your own macros.
|
|
|
|
History of Autoconf
|
|
|
|
* Genesis:: Prehistory and naming of @code{configure}.
|
|
* Exodus:: The plagues of @code{m4} and Perl.
|
|
* Leviticus:: The priestly code of portability arrives.
|
|
* Numbers:: Growth and contributors.
|
|
* Deuteronomy:: Approaching the promises of easy configuration.
|
|
@end menu
|
|
|
|
@node Introduction, Making configure Scripts, Top, Top
|
|
@chapter Introduction
|
|
|
|
@display
|
|
A physicist, an engineer, and a computer scientist were
|
|
discussing the nature of God. Surely a Physicist, said the
|
|
physicist, because early in the Creation, God made Light; and you
|
|
know, the Maxwell's equations, the dual nature of
|
|
electro-magnetic waves, the relativist consequences@dots{} An
|
|
Engineer!, said the engineer, because before making Light, God
|
|
split the Chaos into Land and Water; it takes a hell of an
|
|
engineer to handle that big amount of mud, and orderly separation
|
|
of solids from liquids@dots{} The computer scientist shouted: And
|
|
the Chaos, where do you think it was it coming from, hmm?
|
|
|
|
---Anonymous
|
|
@end display
|
|
@c (via Franc,ois Pinard)
|
|
|
|
Autoconf is a tool for producing shell scripts that automatically
|
|
configure software source code packages to adapt to many kinds of
|
|
UNIX-like systems. The configuration scripts produced by Autoconf are
|
|
independent of Autoconf when they are run, so their users do not need to
|
|
have Autoconf.
|
|
|
|
The configuration scripts produced by Autoconf require no manual user
|
|
intervention when run; they do not normally even need an argument
|
|
specifying the system type. Instead, they test for the presence of each
|
|
feature that the software package they are for might need individually.
|
|
(Before each check, they print a one-line message stating what they are
|
|
checking for, so the user doesn't get too bored while waiting for the
|
|
script to finish.) As a result, they deal well with systems that are
|
|
hybrids or customized from the more common UNIX variants. There is no
|
|
need to maintain files that list the features supported by each release
|
|
of each variant of UNIX.
|
|
|
|
For each software package that Autoconf is used with, it creates a
|
|
configuration script from a template file that lists the
|
|
system features that the package needs or can use. After the shell code to
|
|
recognize and respond to a system feature has been written,
|
|
Autoconf allows it to be shared by many software packages that can
|
|
use (or need) that feature. If it later turns out that the shell code
|
|
needs adjustment for some reason, it needs to be changed in only one
|
|
place; all of the configuration scripts can be regenerated
|
|
automatically to take advantage of the updated code.
|
|
|
|
Larry Wall's Metaconfig package is similar in purpose to Autoconf, but
|
|
the scripts it produces require manual user intervention, which is quite
|
|
inconvenient when configuring large source trees. Unlike Metaconfig
|
|
scripts, Autoconf scripts can support cross-compiling, if some care is
|
|
taken in writing them.
|
|
|
|
Autoconf imposes some restrictions on the names of macros used with
|
|
@code{#ifdef} in C programs (@pxref{Preprocessor Symbol Index}).
|
|
|
|
Autoconf requires GNU @code{m4} in order to generate the scripts. It
|
|
uses features that some UNIX versions of @code{m4} do not have. It also
|
|
overflows internal limits of some versions of @code{m4}, including GNU
|
|
@code{m4} 1.0. You must use version 1.1 or later of GNU @code{m4}.
|
|
Using version 1.3 or later will be much faster than 1.1 or 1.2.
|
|
|
|
@xref{Concerns}, for answers to some common questions about Autoconf.
|
|
@xref{Upgrading}, for information about upgrading from version 1.
|
|
@xref{History}, for the story of Autoconf's development.
|
|
|
|
Mail suggestions and bug reports for Autoconf to
|
|
@code{bug-gnu-utils@@prep.ai.mit.edu}. Please include the Autoconf version
|
|
number, which you can get by running @samp{autoconf --version}.
|
|
|
|
@node Making configure Scripts, Operation, Introduction, Top
|
|
@chapter Making @code{configure} Scripts
|
|
|
|
The configuration scripts that Autoconf produces are by convention
|
|
called @code{configure}. When run, @code{configure} creates several
|
|
files, replacing configuration parameters in them with values
|
|
appropriate for the system being configured. The files that
|
|
@code{configure} creates are:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
one or more @file{Makefile} files, one in each subdirectory of the
|
|
package (@pxref{Makefiles});
|
|
|
|
@item
|
|
optionally, a C header file, the name of which is configurable,
|
|
containing @code{#define} directives (@pxref{Output});
|
|
|
|
@item
|
|
a shell script called @file{config.status} that, when run, will recreate
|
|
the files listed above (@pxref{Invoking config.status});
|
|
|
|
@item
|
|
a shell script called @file{config.cache} that saves the results of
|
|
running many of the tests;
|
|
|
|
@item
|
|
a file called @file{config.log} containing any messages produced by
|
|
compilers, to help debugging if @code{configure} makes a mistake.
|
|
@end itemize
|
|
|
|
To create a @code{configure} script with Autoconf, you need to write an
|
|
Autoconf input file @file{configure.in} and run @code{autoconf} on it.
|
|
If you write your own feature tests to supplement those that come with
|
|
Autoconf, you might also write files called @file{aclocal.m4} and
|
|
@file{acsite.m4}. If you use a C header file to contain @code{#define}
|
|
directives, you might also write @file{acconfig.h}, @file{config.h.top},
|
|
and @file{config.h.bot}, and you will distribute the Autoconf-generated
|
|
file @file{config.h.in} with the package.
|
|
|
|
Here is a diagram showing how the files that can be used in
|
|
configuration are produced. Programs that are executed are suffixed by
|
|
@samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
|
|
@code{autoconf} and @code{autoheader} also read the installed Autoconf
|
|
macro files (by reading @file{autoconf.m4}).
|
|
|
|
@noindent
|
|
Files used in preparing a software package for distribution:
|
|
@example
|
|
@group
|
|
your source files --> [autoscan*] --> [configure.scan] --> configure.in
|
|
|
|
configure.in --. .------> autoconf* -----> configure
|
|
+---+
|
|
[aclocal.m4] --+ `---.
|
|
[acsite.m4] ---' |
|
|
+--> [autoheader*] -> [config.h.in]
|
|
[acconfig.h] ----. |
|
|
+-----'
|
|
[config.h.top] --+
|
|
[config.h.bot] --'
|
|
|
|
Makefile.in -------------------------------> Makefile.in
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
Files used in configuring a software package:
|
|
@example
|
|
@group
|
|
.-------------> config.cache
|
|
configure* ------------+-------------> config.log
|
|
|
|
|
[config.h.in] -. v .-> [config.h] -.
|
|
+--> config.status* -+ +--> make*
|
|
Makefile.in ---' `-> Makefile ---'
|
|
@end group
|
|
@end example
|
|
|
|
@menu
|
|
* Writing configure.in:: What to put in an Autoconf input file.
|
|
* Invoking autoconf:: How to create configuration scripts.
|
|
* Invoking autoheader:: How to create configuration header files.
|
|
* Invoking autoscan:: Semi-automatic @file{configure.in} writing.
|
|
* Invoking ifnames:: Listing the conditionals in source code.
|
|
* Invoking autoreconf:: Remaking multiple @code{configure} scripts.
|
|
* Invoking autoupdate:: Replacing old macro names in @code{configure.in}.
|
|
@end menu
|
|
|
|
@node Writing configure.in, Invoking autoconf, , Making configure Scripts
|
|
@section Writing @file{configure.in}
|
|
|
|
To produce a @code{configure} script for a software package, create a
|
|
file called @file{configure.in} that contains invocations of the
|
|
Autoconf macros that test the system features your package needs or can
|
|
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
|
|
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.
|
|
|
|
Other than that, the order in which @file{configure.in} calls the
|
|
Autoconf macros is generally not important, with a few exceptions.
|
|
Every @file{configure.in} must contain a call to @code{AC_INIT} before
|
|
the checks, and a call to @code{AC_OUTPUT} at the end (@pxref{Output}).
|
|
Additionally, some macros rely on other macros having been called first,
|
|
because they check previously set values of some variables to decide
|
|
what to do. These macros are noted in the individual descriptions
|
|
(@pxref{Existing Tests}), and they also warn you if they are called out
|
|
of order.
|
|
|
|
To encourage consistency, here is a suggested order for calling the
|
|
Autoconf macros.
|
|
|
|
@display
|
|
@group
|
|
@code{AC_INIT(@var{file})}
|
|
checks for alternative programs
|
|
checks for UNIX variants that set C preprocessor variables
|
|
checks for header files
|
|
checks for typedefs
|
|
checks for library functions
|
|
checks for structures
|
|
checks for compiler characteristics
|
|
checks for system services
|
|
other checks for UNIX variants
|
|
@code{AC_OUTPUT(@r{[}@var{file@dots{}}@r{]})}
|
|
@end group
|
|
@end display
|
|
|
|
When calling macros that take arguments, there must not be any blank
|
|
space between the macro name and the open parentheses. Arguments can be
|
|
more than one line long if they are enclosed within the @code{m4} quote
|
|
characters @samp{[} and @samp{]}. Several macros handle two cases: what
|
|
to do if the given condition is met, and what to do if the condition is
|
|
not met. In some places you might want to do something if a
|
|
condition is true but do nothing if it's false, or vice versa. To omit
|
|
the true case, pass an empty value for the @var{action-if-found}
|
|
argument to the macro. To omit the false case, omit the
|
|
@var{action-if-not-found} argument to the macro, including the comma
|
|
before it.
|
|
|
|
You can include comments in @file{configure.in} files by starting them
|
|
with the @code{m4} predefined macro @code{dnl}, which discards text up
|
|
through the next newline. These comments do not appear in the generated
|
|
@code{configure} scripts. For example, it is helpful to begin
|
|
@file{configure.in} files with a line like this:
|
|
|
|
@example
|
|
dnl Process this file with autoconf to produce a configure script.
|
|
@end example
|
|
|
|
@node Invoking autoconf, Invoking autoheader, Writing configure.in, Making configure Scripts
|
|
@section Using @code{autoconf} to Create @file{configure}
|
|
|
|
To create @code{configure} from @file{configure.in}, run the
|
|
@code{autoconf} program with no arguments. @code{autoconf} processes
|
|
@file{configure.in} with the @code{m4} macro processor, using the
|
|
Autoconf macros. If you give @code{autoconf} an argument, it reads that
|
|
file instead of @file{configure.in} and writes the configuration script
|
|
to the standard output instead of to @file{configure}. If you give
|
|
@code{autoconf} the argument @samp{-}, it reads the standard input
|
|
instead of @file{configure.in} and writes the configuration script on
|
|
the standard output.
|
|
|
|
The Autoconf macros are defined in several files. Some of the files are
|
|
distributed with Autoconf; @code{autoconf} reads them first. Then it
|
|
looks for the optional file @file{acsite.m4} in the directory that
|
|
contains the distributed Autoconf macro files, and for the optional file
|
|
@file{aclocal.m4} in the current directory. Those files can contain
|
|
your site's or the package's own Autoconf macro definitions
|
|
(@pxref{Writing Macros}, for more information). If a macro is defined
|
|
in more than one of the files that @code{autoconf} reads, the last
|
|
definition it reads overrides the earlier ones.
|
|
|
|
@evindex AC_MACRODIR
|
|
You can override the directory where @code{autoconf} looks for the
|
|
installed macro files by setting the @code{AC_MACRODIR} environment
|
|
variable to a different directory. You can also give @code{autoconf}
|
|
the @samp{--macrodir} option, which overrides @code{AC_MACRODIR}.
|
|
|
|
@code{autoconf} also accepts the options @code{--version}, which prints
|
|
the Autoconf version number and exits, and @code{--help}, which prints a
|
|
summary of the command-line options and exits.
|
|
|
|
@node Invoking autoheader, Invoking autoscan, Invoking autoconf, Making configure Scripts
|
|
@section Using @code{autoheader} to Create @file{config.h.in}
|
|
|
|
You can use the @code{autoheader} program to create a template file of C
|
|
@samp{#define} statements for @code{configure} to use. By default, the
|
|
file that @code{autoheader} creates is called @file{config.h.in}; if
|
|
@file{configure.in} invokes @code{AC_CONFIG_HEADER(@var{file})},
|
|
@code{autoheader} creates @file{@var{file}.in}.
|
|
|
|
@code{autoheader} scans @file{configure.in} and figures out which C
|
|
preprocessor symbols it might define. It copies comments and
|
|
@code{#define} and @code{#undef} statements from a file called
|
|
@file{acconfig.h}, which comes with and is installed with Autoconf. It
|
|
also uses a file called @file{acconfig.h} in the current directory, if
|
|
present. If you @code{AC_DEFINE} any additional symbols, you must
|
|
create that file with entries for them. For symbols defined by
|
|
@code{AC_CHECK_HEADERS}, @code{AC_CHECK_FUNCS}, @code{AC_CHECK_SIZEOF},
|
|
or @code{AC_CHECK_LIB}, @code{autoheader} generates comments and
|
|
@code{#undef} statements itself rather than copying them from a file,
|
|
since the possible symbols are effectively limitless.
|
|
|
|
The file that @code{autoheader} creates contains mainly @code{#define}
|
|
and @code{#undef} statements and their accompanying comments. If
|
|
@file{./acconfig.h} contains the string @samp{@@TOP@@},
|
|
@code{autoheader} copies the lines before the line containing
|
|
@samp{@@TOP@@} into the top of the file that it generates. Similarly,
|
|
if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
|
|
@code{autoheader} copies the lines after that line to the end of the
|
|
file it generates. Either or both of those strings may be omitted.
|
|
|
|
An obsolete way to produce the same effect is to create the files
|
|
@file{@var{file}.top} (typically @file{config.h.top}) and/or
|
|
@file{@var{file}.bot} in the current directory. If they exist,
|
|
@code{autoheader} copies them to the beginning and end, respectively, of
|
|
its output. Their use is discouraged because they have file names that
|
|
contain two periods, and so can not be stored on MS-DOS; also, they are
|
|
two more files to clutter up the directory. (@pxref{Output}, for more
|
|
information about avoiding file names that MS-DOS cannot store.)
|
|
|
|
If you give @code{autoheader} an argument, it uses that file instead of
|
|
@file{configure.in} and writes the header file to the standard output
|
|
instead of to @file{config.h.in}. If you give @code{autoheader} an
|
|
argument of @samp{-}, it reads the standard input instead of
|
|
@file{configure.in} and writes the header file to the standard output.
|
|
|
|
@evindex AC_MACRODIR
|
|
You can override the directory where @code{autoheader} looks for the
|
|
installed macro and @file{acconfig.h} files by setting the
|
|
@code{AC_MACRODIR} environment variable to a different directory. You
|
|
can also give @code{autoheader} the @samp{--macrodir} option, which
|
|
overrides @code{AC_MACRODIR}.
|
|
|
|
@code{autoheader} also accepts the options @code{--version}, which prints
|
|
the Autoconf version number and exits, and @code{--help}, which prints a
|
|
summary of the command-line options and exits.
|
|
|
|
@node Invoking autoscan, Invoking ifnames, Invoking autoheader, Making configure Scripts
|
|
@section Using @code{autoscan} to Create @file{configure.in}
|
|
|
|
The @code{autoscan} program can help you create a @file{configure.in}
|
|
file for a software package. @code{autoscan} examines source files in
|
|
the directory tree rooted at a directory given as a command line
|
|
argument, or the current directory if none is given. It searches the
|
|
source files for common portability problems and creates a file
|
|
@file{configure.scan} which is a preliminary @file{configure.in} for
|
|
that package.
|
|
|
|
You should manually examine @file{configure.scan} before renaming it to
|
|
@file{configure.in}; it will probably need some adjustments. For
|
|
example, if you want the package to use a configuration header file, you
|
|
will have to add a call to @code{AC_CONFIG_HEADER}. You might have to
|
|
change or add some @code{#if} directives to your program in order to
|
|
make it work with Autoconf (@pxref{Invoking ifnames}, for information
|
|
about a program that might help with that job).
|
|
|
|
@code{autoscan} uses several data files, which are installed with the
|
|
distributed Autoconf macro files, to determine which macros to output
|
|
when it finds particular symbols in a package's source files. These
|
|
files all have the same format. Each line consists of a symbol,
|
|
whitespace, and the Autoconf macro to output if that symbol is
|
|
encountered. Lines starting with @samp{#} are comments.
|
|
|
|
@code{autoscan} is only installed if you already have Perl installed.
|
|
|
|
@code{autoscan} accepts the following options:
|
|
|
|
@table @code
|
|
@item --help
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --macrodir=@var{dir}
|
|
Look for the data files in directory @var{dir} instead of the default
|
|
installation directory.
|
|
|
|
@item --verbose
|
|
Print the names of the files it examines and the potentially interesting
|
|
symbols it finds in them. This output can be voluminous.
|
|
|
|
@item --version
|
|
Print the version number of @code{autoscan} and exit.
|
|
@end table
|
|
|
|
@node Invoking ifnames, Invoking autoreconf, Invoking autoscan, Making configure Scripts
|
|
@section Using @code{ifnames} to List Conditionals
|
|
|
|
@code{ifnames} can help when writing a @file{configure.in} for a
|
|
software package. It prints the identifiers used in C preprocessor
|
|
conditionals. If a package has already been set up to have some
|
|
portability, this program can help you figure out what its
|
|
@code{configure} needs to check for. It may help fill in some gaps in a
|
|
@file{configure.in} generated by @code{autoscan} (@pxref{Invoking autoscan}).
|
|
|
|
@code{ifnames} scans all of the C source files named on the command line
|
|
(or the standard input, if none are given) and writes to the standard
|
|
output a sorted list of all the identifiers that appear in those files
|
|
in @code{#if}, @code{#elif}, or @code{#ifdef} directives. It prints
|
|
each identifier on a line, followed by a space-separated list of the
|
|
files in which that identifier occurs.
|
|
|
|
@noindent
|
|
@code{ifnames} accepts the following options:
|
|
|
|
@table @code
|
|
@item --help
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --macrodir=@var{dir}
|
|
Look for the Autoconf macro files in directory @var{dir} instead of the
|
|
default installation directory. Only used to get the version number.
|
|
|
|
@item --version
|
|
Print the version number of @code{ifnames} and exit.
|
|
@end table
|
|
|
|
@node Invoking autoreconf, Invoking autoupdate, Invoking ifnames, Making configure Scripts
|
|
@section Using @code{autoreconf} to Recreate @file{configure}
|
|
|
|
If you have a lot of Autoconf-generated @code{configure} scripts and you
|
|
get a new version of Autoconf, the @code{autoreconf} program can be
|
|
handy. It runs @code{autoconf} (and @code{autoheader}, where
|
|
appropriate) repeatedly to remake all of the Autoconf @code{configure}
|
|
scripts in a directory tree. @xref{Automatic Remaking}, for further
|
|
information about automatic remaking of @code{configure} scripts.
|
|
|
|
@noindent
|
|
@code{autoreconf} accepts the following options:
|
|
|
|
@table @code
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --macrodir=@var{dir}
|
|
@itemx -m @var{dir}
|
|
Look for the Autoconf macro files in directory @var{dir} instead of the
|
|
default installation directory.
|
|
|
|
@item --verbose
|
|
Print the name of each directory where @code{autoreconf} runs
|
|
@code{autoconf} (and @code{autoheader}, if that directory's
|
|
@file{configure.in} calls @code{AC_CONFIG_HEADER}).
|
|
|
|
@item --version
|
|
Print the version number of @code{autoreconf} and exit.
|
|
@end table
|
|
|
|
@node Invoking autoupdate, , Invoking autoreconf, Making configure Scripts
|
|
@section Using @code{autoupdate} to Modernize @file{configure}
|
|
|
|
The @code{autoupdate} program updates a @file{configure.in} file that
|
|
calls Autoconf macros by their old names to use the current macro names.
|
|
In version 2 of Autoconf, most of the macros were renamed to use a more
|
|
uniform and descriptive naming scheme. @xref{Macro Naming}, for a
|
|
description of the new scheme. Although the old names still work
|
|
(@pxref{Old Macro Names}, for a list of the old macro names and the
|
|
corresponding new names), you can make your @file{configure.in} files
|
|
more readable and make it easier to use the current Autoconf
|
|
documentation if you update them to use the new macro names.
|
|
|
|
@evindex SIMPLE_BACKUP_SUFFIX
|
|
If given no arguments, @code{autoupdate} updates @file{configure.in},
|
|
backing up the original version with the suffix @file{~} (or the value
|
|
of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
|
|
set). If you give @code{autoupdate} an argument, it reads that file
|
|
instead of @file{configure.in} and writes the updated file to the
|
|
standard output.
|
|
|
|
@noindent
|
|
@code{autoupdate} accepts the following options:
|
|
|
|
@table @code
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --macrodir=@var{dir}
|
|
@itemx -m @var{dir}
|
|
Look for the Autoconf macro files in directory @var{dir} instead of the
|
|
default installation directory.
|
|
|
|
@item --version
|
|
Print the version number of @code{autoupdate} and exit.
|
|
@end table
|
|
|
|
@node Operation, Existing Tests, Making configure Scripts, Top
|
|
@chapter Controlling Autoconf Operation
|
|
|
|
These macros control the operation of Autoconf: where it finds files,
|
|
which output files it produces, whether it configures in certain
|
|
optional features of the user's package.
|
|
|
|
@menu
|
|
* Input:: Where Autoconf should find files.
|
|
* Output:: Controlling Autoconf output files.
|
|
* Package Options:: Selecting optional features.
|
|
* Transforming Names:: Changing program names when installing.
|
|
* Versions:: Version numbers in producing @code{configure}.
|
|
@end menu
|
|
|
|
@node Input, Output, , Operation
|
|
@section Finding Autoconf Input
|
|
|
|
The following macros control where Autoconf looks to find files it needs.
|
|
|
|
@defmac AC_CONFIG_AUX_DIR(@var{dir})
|
|
@maindex CONFIG_AUX_DIR
|
|
Use the @file{install.sh}, @file{config.sub}, @file{config.guess}, and
|
|
Cygnus @file{configure} scripts that are in directory @var{dir}. These
|
|
are auxiliary files used in configuration. @var{dir} can be either
|
|
absolute or relative to @file{@var{srcdir}}. The default is
|
|
@file{@var{srcdir}} or @file{@var{srcdir}/..} or
|
|
@file{@var{srcdir}/../..}, whichever is the first that contains
|
|
@file{install.sh}. The other files are not checked for, so that using
|
|
@code{AC_PROG_INSTALL} does not automatically require distributing the
|
|
other auxiliary files.
|
|
@end defmac
|
|
|
|
@defmac AC_INIT (@var{unique-file-in-source-dir})
|
|
@maindex INIT
|
|
Process the command-line arguments and find the source code directory.
|
|
@var{unique-file-in-source-dir} is some file that is in the package's
|
|
source directory; @code{configure} checks for this file's existence to
|
|
make sure that the directory that it is told contains the source code in
|
|
fact does (@pxref{Invoking configure}, for more information). This
|
|
macro is required in every @file{configure.in}.
|
|
@end defmac
|
|
|
|
@node Output, Package Options, Input, Operation
|
|
@section Controlling Autoconf Output
|
|
|
|
The following macros control the kind of output that Autoconf produces.
|
|
|
|
@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{})
|
|
@maindex CONFIG_HEADER
|
|
@cvindex HAVE_CONFIG_H
|
|
Make @code{AC_OUTPUT} create the file(s) in the whitespace-separated
|
|
list @var{header-to-create} containing C preprocessor @code{#define}
|
|
statements, and replace @samp{@@DEFS@@} in generated files with
|
|
@samp{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. The usual
|
|
name for @var{header-to-create} is @file{config.h}.
|
|
|
|
If @var{header-to-create} already exists and its contents are identical
|
|
to what @code{AC_OUTPUT} would put in it, it is left alone. Doing this
|
|
allows some changes in configuration without needlessly causing object
|
|
files that depend on the header file to be recompiled.
|
|
|
|
Your distribution should contain an input file that looks as you want
|
|
the final header file to look, including comments, with default values
|
|
in the @code{#define} statements. A default value can be to
|
|
@code{#undef} the variable instead of to define it to a value, if your
|
|
code tests for configuration options using @code{#ifdef} instead of
|
|
@code{#if}. For example, suppose your @file{configure.in} calls
|
|
@code{AC_CONFIG_HEADER(conf.h)} and @code{AC_CHECK_HEADERS(unistd.h)}.
|
|
You could have code like this in @file{conf.h.in}:
|
|
|
|
@example
|
|
@group
|
|
/* Define as 1 if you have unistd.h. */
|
|
#define HAVE_UNISTD_H 0
|
|
@end group
|
|
@end example
|
|
|
|
On systems that have @file{unistd.h}, @code{configure} will change the 0
|
|
to a 1. On other systems, it will leave the line unchanged.
|
|
Alternately, if you prefer to use @code{#ifdef}, your @file{conf.h.in}
|
|
could have code like this:
|
|
|
|
@example
|
|
@group
|
|
/* Define if you have unistd.h. */
|
|
#undef HAVE_UNISTD_H
|
|
@end group
|
|
@end example
|
|
|
|
On systems that have @file{unistd.h}, @code{configure} will change the
|
|
second line to read @samp{#define HAVE_UNISTD_H 1}. On other systems,
|
|
it will comment that line out (in case the system predefines that symbol).
|
|
|
|
Usually the input file is named @file{@var{header-to-create}.in};
|
|
however, you can override the input file name by appending it to
|
|
@var{header-to-create}, separated by a colon. For example,
|
|
@example
|
|
AC_CONFIG_HEADER(defines.h:defines.hin)
|
|
@end example
|
|
@noindent
|
|
Doing this allows you to keep your filenames acceptable to MS-DOS.
|
|
|
|
You can use the program @code{autoheader} to create the input file
|
|
(@pxref{Invoking autoheader}).
|
|
@end defmac
|
|
|
|
@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
|
|
@maindex CONFIG_SUBDIRS
|
|
@ovindex subdirs
|
|
Run @code{configure} in each subdirectory @var{dir} in the given
|
|
whitespace-separated list. If a given @var{dir} is not found, no error
|
|
is reported, so a @code{configure} script can configure whichever parts
|
|
of a large source tree are present. If a given @var{dir} contains
|
|
@file{configure.in} but no @file{configure}, the Cygnus @code{configure}
|
|
script found by @code{AC_CONFIG_AUXDIR} is used. The subdirectory
|
|
@code{configure} scripts are given the same command line options that
|
|
were given to this @code{configure} script, with minor changes if needed
|
|
(e.g., to adjust a relative path for the cache file or source
|
|
directory). This macro also sets the shell and output variable
|
|
@code{subdirs} to the list of directories @samp{@var{dir} @dots{}}.
|
|
@file{Makefile} rules can use this variable to determine which
|
|
subdirectories to recurse into.
|
|
@end defmac
|
|
|
|
@defmac AC_OUTPUT (@r{[}@var{file}@dots{}@r{] [,}@var{extra-cmds}@r{] [,}@var{init-cmds}@r{]})
|
|
@maindex OUTPUT
|
|
Create output files (typically one or more @file{Makefile}s) and
|
|
@file{config.status}. If @code{AC_CONFIG_HEADER} has been called, also
|
|
create the header file that was named as its argument. The argument is
|
|
a whitespace-separated list of files to create; if it is omitted, no
|
|
files are created. This macro is required in every @file{configure.in}.
|
|
|
|
@code{AC_OUTPUT} creates each file @file{@var{file}} in the list by
|
|
copying an input file (by default named @file{@var{file}.in}),
|
|
substituting the variable values that have been selected by calling
|
|
@code{AC_SUBST}. It creates the directory that each file is in if it
|
|
doesn't exist (but not the parents of that directory). A plausible
|
|
value for the argument to @code{AC_OUTPUT} is @samp{Makefile
|
|
src/Makefile man/Makefile X/Imakefile}. You can override an input file
|
|
name by appending it to @var{file}, separated by a colon. For example,
|
|
@example
|
|
AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk)
|
|
@end example
|
|
|
|
If you pass @var{extra-cmds}, those commands will be inserted into
|
|
@file{config.status} to be run after all its other processing. If
|
|
@var{init-cmds} are given, they are inserted just before
|
|
@var{extra-cmds}, with shell variable, command, and backslash
|
|
substitutions performed on them in @code{configure}. You can use
|
|
@var{init-cmds} to pass variables from @code{configure} to the
|
|
@var{extra-cmds}.
|
|
@end defmac
|
|
|
|
@node Package Options, Transforming Names, Output, Operation
|
|
@section Checking for Package Options
|
|
|
|
These macros check whether the user gave @code{configure} command line
|
|
arguments to select optional features of the package. They may
|
|
take an argument to use if the argument was given and one for if it was
|
|
not given. The argument @var{help-string} is a description of
|
|
the option which looks like this:
|
|
@example
|
|
--enable-editing support fancy command line editing
|
|
@end example
|
|
@noindent
|
|
@var{help-string} may be more than one line long, if more detail is
|
|
needed. Just make sure the columns line up in @samp{configure --help}.
|
|
Avoid tabs in the help string. You'll need to enclose it in @samp{[}
|
|
and @samp{]} in order to produce the leading spaces.
|
|
|
|
@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]})
|
|
@maindex ARG_ENABLE
|
|
If the user gave @code{configure} the option
|
|
@samp{--enable-@var{feature}} or @samp{--disable-@var{feature}}, run
|
|
shell commands @var{action-if-true}. Otherwise run shell commands
|
|
@var{action-if-false}.
|
|
|
|
The name @var{feature} should consist only of alphanumeric characters
|
|
and dashes. The @var{feature} indicates an optional user-level
|
|
facility. This option allows users to choose which optional features to
|
|
build and install. @samp{--enable-@var{feature}} options should never
|
|
make a feature behave differently or cause one feature to replace
|
|
another. They should only cause parts of the program to be built rather
|
|
than left out.
|
|
|
|
The user can give an argument by following the feature name with
|
|
@samp{=} and the argument. Giving an argument of @samp{no} indicates
|
|
that the feature is @emph{not} available. A feature with an argument
|
|
looks like @samp{--enable-debug=stabs}.
|
|
|
|
The argument is available to the shell commands @var{action-if-true} in
|
|
the shell variable @code{enableval}. If no argument was given to
|
|
@samp{--enable-@var{feature}}, @code{enableval} is @samp{yes}.
|
|
@samp{--disable-@var{feature}} is equivalent to
|
|
@samp{--enable-@var{feature}=no}. At present, arguments containing blanks
|
|
are not handled correctly; if you need an argument to contain a list,
|
|
require the items to be separated by commas instead.
|
|
@end defmac
|
|
|
|
@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]})
|
|
@maindex ARG_WITH
|
|
If the user gave @code{configure} the option @samp{--with-@var{package}}
|
|
or @samp{--without-@var{package}}, run shell commands
|
|
@var{action-if-true}. Otherwise run shell commands
|
|
@var{action-if-false}.
|
|
|
|
The name @var{package} should consist only of alphanumeric characters
|
|
and dashes. The @var{package} indicates another software package that
|
|
this program should work with. For example, @samp{--with-gnu-ld} means
|
|
work with the GNU linker instead of some other linker.
|
|
@samp{--with-x11} means work with X11.
|
|
|
|
The user can give an argument by following the package name with
|
|
@samp{=} and the argument. Giving an argument of @samp{no} is for
|
|
packages that would be used by default; it says to @emph{not} use the
|
|
package. An argument that is neither @samp{yes} nor @samp{no} could
|
|
include a name or number of a version of the other package, to specify
|
|
more precisely which other package this program is supposed to work
|
|
with.
|
|
|
|
The argument is available to the shell commands @var{action-if-true} in
|
|
the shell variable @code{withval}. If no argument was given to
|
|
@samp{--with-@var{package}}, @code{withval} is @samp{yes}.
|
|
@samp{--without-@var{package}} is equivalent to
|
|
@samp{--with-@var{package}=no}. At present, arguments containing blanks
|
|
are not handled correctly; if you need an argument to contain a list,
|
|
require the items to be separated by commas instead.
|
|
@end defmac
|
|
|
|
@defmac AC_ENABLE (@var{feature}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]})
|
|
@maindex ENABLE
|
|
This is an obsolete version of @code{AC_ARG_ENABLE} that does not
|
|
support providing a help string.
|
|
@end defmac
|
|
|
|
@defmac AC_WITH (@var{package}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]})
|
|
@maindex WITH
|
|
This is an obsolete version of @code{AC_ARG_WITH} that does not
|
|
support providing a help string.
|
|
@end defmac
|
|
|
|
@node Transforming Names, Versions, Package Options, Operation
|
|
@section Transforming Program Names When Installing
|
|
|
|
Autoconf supports giving @code{configure} the following command line
|
|
options to change the names of programs being installed:
|
|
|
|
@table @code
|
|
@item --program-prefix=@var{prefix}
|
|
prepend @var{prefix} to the names;
|
|
|
|
@item --program-suffix=@var{suffix}
|
|
append @var{suffix} to the names;
|
|
|
|
@item --program-transform-name=@var{expression}
|
|
perform @code{sed} substitution @var{expression} on the names. The main
|
|
use for this option is to prevent the automatic addition of a target
|
|
name prefix to program names (see below) by giving an empty
|
|
@var{expression}. As another possibility,
|
|
@samp{--program-transform-name='s,^\(........\).*,\1.exe,'} could be used to
|
|
truncate installed program names to 8 characters and append @file{.exe}.
|
|
@end table
|
|
|
|
In order to use the values given to those options, @file{configure.in}
|
|
must call the macro @code{AC_ARG_PROGRAM}.
|
|
|
|
@defmac AC_ARG_PROGRAM
|
|
@maindex ARG_PROGRAM
|
|
@ovindex program_transform_name
|
|
Place in output variable @code{program_transform_name} a
|
|
sequence of @code{sed} commands for changing the names of installed
|
|
programs.
|
|
|
|
If any of the above options are given to @code{configure}, program names
|
|
are transformed accordingly. Otherwise, if @code{AC_CANONICAL_SYSTEM}
|
|
has been called and a @samp{--target} value is given that differs from
|
|
the host type (specified with @samp{--host} or defaulted by
|
|
@code{config.sub}), the target type followed by a dash is used as a
|
|
prefix. Otherwise, no program name transformation is done.
|
|
|
|
These transformations are useful with programs that can be part of a
|
|
cross-compilation development environment. For example, a
|
|
cross-assembler running on a Sun 4 configured with
|
|
@samp{--target=i960-vxworks} is normally installed as
|
|
@file{i960-vxworks-as}, rather than @file{as}, which could be confused
|
|
with a native Sun 4 assembler.
|
|
|
|
They can also force a program name to begin with @file{g}, if you don't
|
|
want GNU programs installed on your system to shadow system programs by
|
|
the same name. For example, if GNU @code{make} used this macro, you
|
|
could configure it with @samp{--program-prefix=g} and when you ran
|
|
@samp{make install}, it would be installed as
|
|
@file{/usr/local/bin/gmake}.
|
|
|
|
Use the variable @code{program_transform_name} as in this example for
|
|
an assembler, compiled as @file{as.new}. The shell variable @code{t}
|
|
is needed in case @code{program_transform_name} contains any shell
|
|
special characters. With quoting and variable substitutions, whitespace
|
|
still properly separates @code{sed} arguments, but other special
|
|
characters have no effect.
|
|
|
|
@example
|
|
program_transform_name=@@program_transform_name@@
|
|
install: all
|
|
name=`t='$(program_transform_name)'; echo as | sed $$t` ; \
|
|
$(INSTALL_PROGRAM) as.new $(bindir)/$$name
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Versions, , Transforming Names, Operation
|
|
@section Controlling Autoconf Versions
|
|
|
|
The following macros manage version numbers for @code{configure} scripts.
|
|
|
|
@defmac AC_PREREQ (@var{version})
|
|
@maindex PREREQ
|
|
Ensure that a recent enough version of Autoconf is being used. If the
|
|
version of Autoconf being used to create @code{configure} is earlier
|
|
than @var{version}, print an error message on the standard error output
|
|
and do not create @code{configure}. For example:
|
|
|
|
@example
|
|
AC_PREREQ(1.8)
|
|
@end example
|
|
|
|
This macro is useful if your @file{configure.in} relies on non-obvious
|
|
behavior that changed between Autoconf releases. If it merely needs
|
|
recently added macros, then @code{AC_PREREQ} is less useful, because the
|
|
@code{autoconf} program already tells the user which macros are not
|
|
found. The same thing happens if @file{configure.in} is processed by a
|
|
version of Autoconf older than when @code{AC_PREREQ} was added.
|
|
@end defmac
|
|
|
|
@defmac AC_REVISION (@var{revision-info})
|
|
@maindex REVISION
|
|
Copy revision stamp @var{revision-info} into the @file{configure}
|
|
script, with any dollar signs or double-quotes removed. This macro lets
|
|
you put a revision stamp from @file{configure.in} into @file{configure}
|
|
without RCS or CVS changing it when you check in @file{configure}. That
|
|
way, you can determine easily which revision of @file{configure.in} a
|
|
particular @file{configure} corresponds to.
|
|
|
|
It is a good idea to call this macro before @code{AC_INIT} so that the
|
|
revision number is near the top of both @file{configure.in} and
|
|
@file{configure}. To support doing that, the @code{AC_REVISION} output
|
|
begins with @samp{#!/bin/sh}, like the normal start of a
|
|
@file{configure} script does.
|
|
|
|
For example, this line in @file{configure.in}:
|
|
|
|
@c The asis prevents RCS from changing the example in the manual.
|
|
@example
|
|
AC_REVISION($@asis{Revision: 1.30 }$)dnl
|
|
@end example
|
|
|
|
@noindent
|
|
produces this in @file{configure}:
|
|
|
|
@example
|
|
#!/bin/sh
|
|
# From configure.in Revision: 1.30
|
|
@end example
|
|
@end defmac
|
|
|
|
@node Existing Tests, Primitives, 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}).
|
|
|
|
Some of these macros set variables whose values can be substituted into
|
|
output files. @xref{Setting Variables}, for details on how this is
|
|
done. The phrase ``define @var{name}'' is used below as a shorthand to
|
|
mean either add @samp{-D@var{name}=1} to the output variable
|
|
@code{DEFS}, or put @samp{#define @var{name} 1} in the configuration
|
|
header file, depending on whether @code{AC_CONFIG_HEADER} has been
|
|
called. @xref{Output}, for more information on @code{AC_CONFIG_HEADER}.
|
|
|
|
Within each section below, the macros are listed in alphabetical order.
|
|
The macros are generally named for the output variables or C
|
|
preprocessor macros that they define; those names are based largely on
|
|
what existing GNU programs use.
|
|
|
|
@menu
|
|
* Alternative Programs:: Selecting between alternative programs.
|
|
* Libraries:: Library archives that might be missing.
|
|
* Header Files:: Header files that might be missing.
|
|
* Typedefs:: @code{typedef}s that might be missing.
|
|
* Library Functions:: C library functions that might be missing.
|
|
* Structures:: Structures or members that might be missing.
|
|
* Compiler Characteristics:: C compiler or machine architecture features.
|
|
* System Services:: Operating system services.
|
|
* UNIX Variants:: Special cases for specific UNIX variants.
|
|
@end menu
|
|
|
|
@node Alternative Programs, Libraries, , Existing Tests
|
|
@section Alternative Programs
|
|
|
|
These macros check for the presence or behavior of particular programs.
|
|
They are used to choose between several alternative programs and to
|
|
decide what to do once one has been chosen.
|
|
If there is no macro specifically defined to check for a program you need,
|
|
and you don't need to check for any special properties of
|
|
it, then you can use one of the general program check macros.
|
|
|
|
@menu
|
|
* Particular Programs:: Special handling to find certain programs.
|
|
* Generic Programs:: How to find other programs.
|
|
@end menu
|
|
|
|
@node Particular Programs, Generic Programs, , Alternative Programs
|
|
@subsection Checks For Particular Programs
|
|
|
|
These macros check for particular programs.
|
|
|
|
@defmac AC_DECL_YYTEXT
|
|
@maindex DECL_YYTEXT
|
|
@cvindex YYTEXT_POINTER
|
|
@ovindex LEX_OUTPUT_ROOT
|
|
Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
|
|
of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
|
|
the base of the file name that the lexer generates; usually
|
|
@file{lex.yy}, but sometimes something else. These results vary
|
|
according to whether @code{lex} or @code{flex} is being used. This
|
|
macro calls @code{AC_PROG_CPP} (or @code{AC_PROG_CXXCPP} if C++ is the
|
|
current language, @pxref{Language Choice}) and @code{AC_PROG_LEX} if
|
|
they haven't been called already.
|
|
|
|
This macro replaces @code{AC_DECLARE_YYTEXT}, which didn't work reliably.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_AWK
|
|
@maindex PROG_AWK
|
|
@ovindex AWK
|
|
Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that
|
|
order, and set output variable @code{AWK} to the first one that it
|
|
finds.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CC
|
|
@maindex PROG_CC
|
|
@ovindex CC
|
|
@ovindex CFLAGS
|
|
Determine a C compiler to use. If @code{CC} is not already set in the
|
|
environment, check for @code{gcc}, and use @code{cc} if it's not found.
|
|
Set output variable @code{CC} to the name of the compiler found.
|
|
|
|
If using the GNU C compiler, set shell variable @code{GCC} to
|
|
@samp{yes}, empty otherwise. If output variable @code{CFLAGS} was
|
|
not already set, set it to @samp{-g -O} for the GNU C compiler
|
|
(@samp{-O} on systems where GCC does not accept @samp{-g}), or @samp{-g}
|
|
for other compilers.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CC_C_O
|
|
@maindex PROG_CC_C_O
|
|
@cvindex NO_MINUS_C_MINUS_O
|
|
If the C compiler does not accept the @samp{-c} and @samp{-o} options
|
|
simultaneously, define @code{NO_MINUS_C_MINUS_O}.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CPP
|
|
@maindex PROG_CPP
|
|
@ovindex CPP
|
|
Set shell and output variable @code{CPP} to a command that runs the
|
|
C preprocessor. If @samp{$CC -E} doesn't work, it uses @file{/lib/cpp}.
|
|
It is only portable to run @code{CPP} on files with a @file{.c}
|
|
extension.
|
|
|
|
If the current language is C (@pxref{Language Choice}), many of the
|
|
specific test macros use the value of @code{CPP} indirectly by calling
|
|
@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or
|
|
@code{AC_EGREP_CPP}. Those macros call this macro first if it
|
|
hasn't been called already. It calls @code{AC_PROG_CC} if it hasn't
|
|
been called already.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CXX
|
|
@maindex PROG_CXX
|
|
@ovindex CXX
|
|
@ovindex CXXFLAGS
|
|
Determine a C++ compiler to use. Check if the environment variable
|
|
@code{CXX} or @code{CCC} (in that order) is set; if so, set output
|
|
variable @code{CXX} to its value. Otherwise search for a C++ compiler
|
|
under likely names (@code{c++}, @code{g++}, @code{gcc}, @code{CC}, and
|
|
@code{cxx}). If none of those checks succeed, as a last resort set
|
|
@code{CXX} to @code{gcc}.
|
|
|
|
If using the GNU C++ compiler, set shell variable @code{GXX} to
|
|
@samp{yes}, empty otherwise. If output variable @code{CXXFLAGS} was
|
|
not already set, set it to @samp{-g -O} for the GNU C++ compiler
|
|
(@samp{-O} on systems where G++ does not accept @samp{-g}), or @samp{-g}
|
|
for other compilers.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CXXCPP
|
|
@maindex PROG_CXXCPP
|
|
@ovindex CXXCPP
|
|
Set shell and output variable @code{CXXCPP} to a command that runs the
|
|
C++ preprocessor. If @samp{$CXX -E} doesn't work, it uses @file{/lib/cpp}.
|
|
It is only portable to run @code{CXXCPP} on files with a @file{.c},
|
|
@file{.C}, or @file{.cc} extension.
|
|
|
|
If the current language is C++ (@pxref{Language Choice}), many of the
|
|
specific test macros use the value of @code{CXXCPP} indirectly by
|
|
calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER},
|
|
@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}. Those macros call
|
|
this macro first if it hasn't been called already. This macro calls
|
|
@code{AC_PROG_CXX} if it hasn't been called already.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_GCC_TRADITIONAL
|
|
@maindex PROG_GCC_TRADITIONAL
|
|
@ovindex CC
|
|
Add @samp{-traditional} to output variable @code{CC} if using the
|
|
GNU C compiler and @code{ioctl} does not work properly without
|
|
@samp{-traditional}. That usually happens when the fixed header files
|
|
have not been installed on an old system. Since recent versions of the
|
|
GNU C compiler fix the header files automatically when installed, this
|
|
is becoming a less prevalent problem. This macro calls
|
|
@code{AC_PROG_CC} and @code{AC_PROG_CPP} if they haven't been called
|
|
already.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_INSTALL
|
|
@maindex PROG_INSTALL
|
|
@ovindex INSTALL
|
|
@ovindex INSTALL_PROGRAM
|
|
@ovindex INSTALL_DATA
|
|
Set output variable @code{INSTALL} to the path of a BSD compatible
|
|
@code{install} program, if one is found in the current @code{PATH}.
|
|
Otherwise, set @code{INSTALL} to @samp{@var{dir}/install.sh -c}, where
|
|
it checks the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
|
|
default directories) to determine @var{dir} (@pxref{Output}).
|
|
|
|
This macro screens out various instances of @code{install} known to not
|
|
work. It also sets the variable @code{INSTALL_PROGRAM} to
|
|
@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m
|
|
644}.
|
|
|
|
If you need to use your own installation program because it has features
|
|
not found in standard @code{install} programs, there is no reason to use
|
|
@code{AC_PROG_INSTALL}; just put the pathname of your program into your
|
|
@file{Makefile.in} files.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_LEX
|
|
@maindex PROG_LEX
|
|
@ovindex LEX
|
|
@ovindex LEXLIB
|
|
If @code{flex} is found, set output variable @code{LEX} to
|
|
@samp{flex} and @code{LEXLIB} to @samp{-lfl}, if that library is in a
|
|
standard place. Otherwise set @code{LEX} to @samp{lex} and
|
|
@code{LEXLIB} to @samp{-ll}.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_LN_S
|
|
@maindex PROG_LN_S
|
|
@ovindex LN_S
|
|
If @samp{ln -s} works on the current filesystem (the operating system
|
|
and filesystem support symbolic links), set shell and output
|
|
variable @code{LN_S} to @samp{ln -s}, otherwise set it to @samp{ln}.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_MAKE_SET
|
|
@maindex PROG_MAKE_SET
|
|
@ovindex SET_MAKE
|
|
If @code{make} predefines the variable @code{MAKE}, define output
|
|
variable @code{SET_MAKE} to be empty. Otherwise, define @code{SET_MAKE}
|
|
to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for @code{SET_MAKE}.
|
|
|
|
In recent versions of @code{make}, the variable @code{MAKE} contains the
|
|
name of the @code{make} program plus options it was given. It is used
|
|
when running @code{make} recursively in subdirectories. But some old
|
|
versions of @code{make} don't set the @code{MAKE} variable.
|
|
This macro allows use of @code{MAKE} on all systems.
|
|
|
|
If you use this macro, simply place a line like this in your
|
|
@file{Makefile.in} file(s):
|
|
|
|
@example
|
|
@@SET_MAKE@@
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_RANLIB
|
|
@maindex PROG_RANLIB
|
|
@ovindex RANLIB
|
|
Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
|
|
is found, otherwise to @samp{:} (do nothing).
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_YACC
|
|
@maindex PROG_YACC
|
|
@ovindex YACC
|
|
If @code{bison} is found, set output variable @code{YACC} to
|
|
@samp{bison -y}. Otherwise, if @code{byacc} is found, set @code{YACC}
|
|
to @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
|
|
@end defmac
|
|
|
|
@node Generic Programs, , Particular Programs, Alternative Programs
|
|
@subsection Generic Program Checking Macros
|
|
|
|
These macros are used to find programs not covered by the particular
|
|
test macros.
|
|
|
|
@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found} @r{[}, @var{value-if-not-found}@r{]})
|
|
@maindex CHECK_PROG
|
|
Check whether program @var{prog-to-check-for} exists in @code{PATH}. If
|
|
it is found, set @var{variable} to @var{value-if-found}, otherwise to
|
|
@var{value-if-not-found}, if given. If @var{variable} was already set,
|
|
do nothing. Calls @code{AC_SUBST} for @var{variable}.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found}@r{]})
|
|
@maindex CHECK_PROGS
|
|
Check for each program in the whitespace-separated list
|
|
@var{progs-to-check-for} exists in @code{PATH}. If it is found, set
|
|
@var{variable} to the name of that program. Otherwise, continue
|
|
checking the next program in the list. If none of the programs in the
|
|
list are found, set @var{variable} to @var{value-if-not-found}; if
|
|
@var{value-if-not-found} is not specified, the value of @var{variable}
|
|
is not changed. Calls @code{AC_SUBST} for @var{variable}.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found}@r{]})
|
|
@maindex PATH_PROG
|
|
Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire
|
|
path of @var{prog-to-check-for} if found.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found}@r{]})
|
|
@maindex PATH_PROGS
|
|
Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
|
|
are found, set @var{variable} to the entire pathname of the program
|
|
found.
|
|
@end defmac
|
|
|
|
@defmac AC_PREFIX_PROGRAM (@var{program})
|
|
@maindex PREFIX_PROGRAM
|
|
If the user did not specify an installation prefix (using the
|
|
@samp{--prefix} option), guess a value for it by looking for
|
|
@var{program} in @code{PATH}, the way the shell does. If @var{program}
|
|
is found, set the prefix to the parent of the directory containing
|
|
@var{program}; otherwise leave the prefix specified in
|
|
@file{Makefile.in} unchanged. For example, if @var{program} is
|
|
@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc},
|
|
set the prefix to @file{/usr/local/gnu}.
|
|
@end defmac
|
|
|
|
@node Libraries, Header Files, Alternative Programs, Existing Tests
|
|
@section Library Files
|
|
|
|
The following macros check for the presence of certain C library archive
|
|
files.
|
|
|
|
@defmac AC_CHECK_LIB (@var{library}, @var{function}, @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found} @r{[}, @var{other-libraries}@r{]]]})
|
|
@maindex CHECK_LIB
|
|
Create a test C program to see whether that program can be linked with
|
|
the library @var{library}. @var{function} should be the name of a
|
|
function that that library contains, to force the linker to try to link
|
|
with the library to resolve the name. @var{library} must be the base
|
|
name of the library; e.g., to check for @samp{-lmp}, use @samp{mp} as
|
|
the @var{library} argument.
|
|
|
|
@var{action-if-found} is a list of shell commands to run if the link
|
|
succeeds (which means that the library is present);
|
|
@var{action-if-not-found} is a list of shell commands to run if the link
|
|
fails. If @var{action-if-found} and @var{action-if-not-found} are not
|
|
specified, the default action is to add @samp{-l@var{library}} to
|
|
@code{LIBS} and define @samp{HAVE_LIB@var{library}}.
|
|
|
|
If linking with @var{library} results in unresolved symbols, which would
|
|
be resolved by linking with additional libraries, give those libraries
|
|
as the @var{other-libraries} argument, separated by spaces: @samp{-lX11
|
|
-lXt}. Otherwise this macro will fail to detect that @var{library} is
|
|
present, because linking the test program will always fail with
|
|
unresolved symbols.
|
|
@end defmac
|
|
|
|
@defmac AC_HAVE_LIBRARY (@var{library}, @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found} @r{[}, @var{other-libraries}@r{]]]})
|
|
@maindex HAVE_LIBRARY
|
|
This macro is equivalent to calling @code{AC_CHECK_LIB} with a
|
|
@var{function} argument of @code{main}. In addition, @var{library} can
|
|
be written as any of @samp{foo}, @samp{-lfoo}, or @samp{libfoo.a}. In
|
|
all of those cases, the compiler is passed @samp{-lfoo}. However,
|
|
@var{library} can not be a shell variable; it must be a literal name.
|
|
This macro is considered obsolete.
|
|
@end defmac
|
|
|
|
@node Header Files, Typedefs, Libraries, Existing Tests
|
|
@section Header Files
|
|
|
|
The following macros check for the presence of certain C header files.
|
|
If there is no macro specifically defined to check for a header file you need,
|
|
and you don't need to check for any special properties of
|
|
it, then you can use one of the general header file check macros.
|
|
|
|
@menu
|
|
* Particular Headers:: Special handling to find certain headers.
|
|
* Generic Headers:: How to find other headers.
|
|
@end menu
|
|
|
|
@node Particular Headers, Generic Headers, , Header Files
|
|
@subsection Checks For Particular Headers
|
|
|
|
These macros check for particular system header files.
|
|
|
|
@defmac AC_DECL_SYS_SIGLIST
|
|
@maindex DECL_SYS_SIGLIST
|
|
@cvindex SYS_SIGLIST_DECLARED
|
|
Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist} is
|
|
declared in a system header file, either @file{signal.h} or
|
|
@file{unistd.h}.
|
|
@end defmac
|
|
|
|
@defmac AC_DIR_HEADER
|
|
@maindex DIR_HEADER
|
|
@cvindex DIRENT
|
|
@cvindex SYSDIR
|
|
@cvindex SYSNDIR
|
|
@cvindex NDIR
|
|
@cvindex VOID_CLOSEDIR
|
|
Like calling @code{AC_HEADER_DIRENT} and @code{AC_FUNC_CLOSEDIR_VOID},
|
|
but defines a different set of C preprocessor macros to indicate which
|
|
header file is found. This macro and the names it defines are
|
|
considered obsolete. The names it defines are:
|
|
|
|
@table @file
|
|
@item dirent.h
|
|
@code{DIRENT}
|
|
|
|
@item sys/ndir.h
|
|
@code{SYSNDIR}
|
|
|
|
@item sys/dir.h
|
|
@code{SYSDIR}
|
|
|
|
@item ndir.h
|
|
@code{NDIR}
|
|
@end table
|
|
|
|
If the @code{closedir} function does not return a meaningful value,
|
|
define @code{VOID_CLOSEDIR}.
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_DIRENT
|
|
@maindex HEADER_DIRENT
|
|
@cvindex HAVE_DIRENT_H
|
|
@cvindex HAVE_NDIR_H
|
|
@cvindex HAVE_SYS_DIR_H
|
|
@cvindex HAVE_SYS_NDIR_H
|
|
Check for the following header files, and for the first one that is
|
|
found and defines @samp{DIR}, define the listed C preprocessor macro:
|
|
|
|
@table @file
|
|
@item dirent.h
|
|
@code{HAVE_DIRENT_H}
|
|
|
|
@item sys/ndir.h
|
|
@code{HAVE_SYS_NDIR_H}
|
|
|
|
@item sys/dir.h
|
|
@code{HAVE_SYS_DIR_H}
|
|
|
|
@item ndir.h
|
|
@code{HAVE_NDIR_H}
|
|
@end table
|
|
|
|
The directory library declarations in the source code should look
|
|
something like the following, which assumes that you have also called
|
|
@samp{AC_CHECK_HEADERS(unistd.h)}:
|
|
|
|
@example
|
|
@group
|
|
#ifdef HAVE_UNISTD_H
|
|
# include <sys/types.h>
|
|
# include <unistd.h>
|
|
#endif
|
|
|
|
#ifdef HAVE_DIRENT_H
|
|
# include <dirent.h>
|
|
# define NAMLEN(dirent) (strlen((dirent)->d_name))
|
|
#else
|
|
# define dirent direct
|
|
# define NAMLEN(dirent) ((dirent)->d_namlen)
|
|
# ifdef HAVE_SYS_NDIR_H
|
|
# include <sys/ndir.h>
|
|
# endif
|
|
# ifdef HAVE_SYS_DIR_H
|
|
# include <sys/dir.h>
|
|
# endif
|
|
# ifdef HAVE_NDIR_H
|
|
# include <ndir.h>
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
Using the above declarations, the program would declare variables to be
|
|
type @code{struct dirent}, not @code{struct direct}, and would access
|
|
the length of a directory entry name by passing a pointer to a
|
|
@code{struct dirent} to the @code{NAMLEN} macro.
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_MAJOR
|
|
@maindex HEADER_MAJOR
|
|
@cvindex MAJOR_IN_MKDEV
|
|
@cvindex MAJOR_IN_SYSMACROS
|
|
If @file{sys/types.h} does not define @code{major}, @code{minor}, and
|
|
@code{makedev}, but @file{sys/mkdev.h} does, define
|
|
@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
|
|
@code{MAJOR_IN_SYSMACROS}.
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_STDC
|
|
@maindex HEADER_STDC
|
|
@cvindex STDC_HEADERS
|
|
Define @code{STDC_HEADERS} if the system has ANSI C header files.
|
|
Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
|
|
@file{string.h}, and @file{float.h}; if the system has those, it
|
|
probably has the rest of the ANSI C header files. This macro also
|
|
checks whether @file{string.h} declares @code{memchr} (and thus
|
|
presumably the other @code{mem} functions), whether @file{stdlib.h}
|
|
declare @code{free} (and thus presumably @code{malloc} and other related
|
|
functions), and whether the @file{ctype.h} macros work on characters
|
|
with the high bit set, as ANSI C requires.
|
|
|
|
Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
|
|
the system has ANSI-compliant header files (and probably C library
|
|
functions) because many systems that have GCC do not have ANSI C header
|
|
files.
|
|
|
|
On systems without ANSI C headers, there is so much variation that it is
|
|
probably easier to declare the functions you use than to figure out
|
|
exactly what the system header files declare. Some systems contain a
|
|
mix of functions ANSI and BSD; some are mostly ANSI but lack
|
|
@samp{memmove}; some define the BSD functions as macros in
|
|
@file{string.h} or @file{strings.h}; some have only the BSD functions
|
|
but @file{string.h}; some declare the memory functions in
|
|
@file{memory.h}, some in @file{string.h}; etc. It is probably
|
|
sufficient to check for one string function and one memory function; if
|
|
the library has the ANSI versions of those then it probably has most of
|
|
the others. If you put the following in @file{configure.in}:
|
|
|
|
@example
|
|
AC_HEADER_STDC
|
|
AC_CHECK_FUNCS(strchr memcpy)
|
|
@end example
|
|
|
|
@noindent
|
|
then, in your code, you can put declarations like this:
|
|
|
|
@example
|
|
@group
|
|
#if STDC_HEADERS
|
|
# include <string.h>
|
|
#else
|
|
# ifndef HAVE_STRCHR
|
|
# define strchr index
|
|
# define strrchr rindex
|
|
# endif
|
|
char *strchr (), *strrchr ();
|
|
# ifndef HAVE_MEMCPY
|
|
# define memcpy(d, s, n) bcopy ((s), (d), (n))
|
|
# define memmove(d, s, n) bcopy ((s), (d), (n))
|
|
# define memcmp(s1, s2, n) bcmp ((s1), (s2), (n))
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
If you use a function like @code{memchr}, @code{memset}, @code{strtok},
|
|
or @code{strspn}, which have no BSD equivalent, then macros won't
|
|
suffice; you must provide an implementation of each function. An easy
|
|
way to incorporate your implementations only when needed (since the ones
|
|
in system C libraries may be hand optimized) is to, taking @code{memchr}
|
|
for example, put it in @file{memchr.c} and use
|
|
@samp{AC_REPLACE_FUNCS(memchr)}.
|
|
|
|
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.
|
|
@end defmac
|
|
|
|
@defmac AC_MEMORY_H
|
|
@maindex MEMORY_H
|
|
@cvindex NEED_MEMORY_H
|
|
Define @code{NEED_MEMORY_H} if @code{memcpy}, @code{memcmp}, etc. are
|
|
not declared in @file{string.h} and @file{memory.h} exists. This macro
|
|
is obsolete; instead, use @code{AC_CHECK_HEADERS(memory.h)}. See the
|
|
example for @code{AC_HEADER_STDC}.
|
|
@end defmac
|
|
|
|
@defmac AC_UNISTD_H
|
|
@maindex UNISTD_H
|
|
@cvindex HAVE_UNISTD_H
|
|
Define @code{HAVE_UNISTD_H} if the system has @file{unistd.h}. This
|
|
macro is obsolete; instead, use @samp{AC_CHECK_HEADERS(unistd.h)}.
|
|
|
|
The way to check if the system supports POSIX.1 is:
|
|
|
|
@example
|
|
@group
|
|
#if HAVE_UNISTD_H
|
|
# include <sys/types.h>
|
|
# include <unistd.h>
|
|
#endif
|
|
|
|
#ifdef _POSIX_VERSION
|
|
/* Code for POSIX.1 systems. */
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
@cvindex _POSIX_VERSION
|
|
@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
|
|
POSIX.1 systems. If there is no @file{unistd.h}, it is definitely not a
|
|
POSIX.1 system. However, some non-POSIX.1 systems do have @file{unistd.h}.
|
|
@end defmac
|
|
|
|
@defmac AC_USG
|
|
@maindex USG
|
|
@cvindex USG
|
|
Define @code{USG} if the system does not have @file{strings.h},
|
|
@code{rindex}, @code{bzero}, etc. This implies that it has
|
|
@file{string.h}, @code{strrchr}, @code{memset}, etc.
|
|
|
|
The symbol @code{USG} is obsolete. Instead of this macro, use
|
|
@code{AC_CHECK_HEADERS(string.h)} and use @code{HAVE_STRING_H} in your
|
|
code. See the example for @code{AC_HEADER_STDC}.
|
|
@end defmac
|
|
|
|
@node Generic Headers, , Particular Headers, Header Files
|
|
@subsection Generic Header Checking Macros
|
|
|
|
These macros are used to find system header files not covered by the
|
|
particular test macros.
|
|
|
|
@defmac AC_CHECK_HEADER (@var{header-file}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]})
|
|
@maindex CHECK_HEADER
|
|
If the system header file @var{header-file} exists, execute shell commands
|
|
@var{action-if-found}, otherwise execute @var{action-if-not-found}. If
|
|
you just want to define a symbol if the header file is available,
|
|
consider using @code{AC_CHECK_HEADERS} instead.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_HEADERS (@var{header-file}@dots{} @r{[}, @var{action}@r{]})
|
|
@maindex CHECK_HEADERS
|
|
@cvindex HAVE_@var{header}
|
|
For each given system header file @var{header-file} in the
|
|
whitespace-separated argument list that exists, define
|
|
@code{HAVE_@var{header-file}} (in all caps). @xref{Existing Tests}, for
|
|
a precise definition of ``define'' as it is used here.
|
|
If @var{action} is given, it is additional shell code to execute
|
|
when one of the header files is found. You can give an @var{action} of
|
|
@samp{break} to break out of the loop on the first match.
|
|
@end defmac
|
|
|
|
@node Typedefs, Library Functions, Header Files, Existing Tests
|
|
@section Typedefs
|
|
|
|
The following macros check for predefined C types.
|
|
If there is no macro specifically defined to check for a type you need,
|
|
and you don't need to check for any special properties of
|
|
it, then you can use one of the general type check macros.
|
|
|
|
@menu
|
|
* Particular Types:: Special handling to find certain types.
|
|
* Generic Types:: How to find other types.
|
|
@end menu
|
|
|
|
@node Particular Types, Generic Types, , Typedefs
|
|
@subsection Checks For Particular Types
|
|
|
|
These macros check for particular C types.
|
|
|
|
@defmac AC_TYPE_GETGROUPS
|
|
@maindex TYPE_GETGROUPS
|
|
@cvindex GETGROUPS_T
|
|
Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
|
|
is the base type of the array argument to @code{getgroups}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_MODE_T
|
|
@maindex TYPE_MODE_T
|
|
@cvindex mode_t
|
|
If @code{mode_t} is not defined in @file{sys/types.h}, define
|
|
@code{mode_t} to be @code{int}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_OFF_T
|
|
@maindex TYPE_OFF_T
|
|
@cvindex off_t
|
|
If @code{off_t} is not defined in @file{sys/types.h}, define
|
|
@code{off_t} to be @code{long}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_PID_T
|
|
@maindex TYPE_PID_T
|
|
@cvindex pid_t
|
|
If @code{pid_t} is not defined in @file{sys/types.h}, define
|
|
@code{pid_t} to be @code{int}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_SIGNAL
|
|
@maindex TYPE_SIGNAL
|
|
@cvindex RETSIGTYPE
|
|
If @file{signal.h} declares @code{signal} as returning a pointer to a
|
|
function returning @code{void}, define @code{RETSIGTYPE} to be
|
|
@code{void}; otherwise, define it to be @code{int}.
|
|
|
|
Define signal handlers as returning type @code{RETSIGTYPE}:
|
|
|
|
@example
|
|
@group
|
|
RETSIGTYPE
|
|
hup_handler ()
|
|
@{
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_SIZE_T
|
|
@maindex TYPE_SIZE_T
|
|
@cvindex size_t
|
|
If @code{size_t} is not defined in @file{sys/types.h}, define
|
|
@code{size_t} to be @code{unsigned}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_UID_T
|
|
@maindex TYPE_UID_T
|
|
@cvindex uid_t
|
|
@cvindex gid_t
|
|
If @code{uid_t} is not defined in @file{sys/types.h}, define
|
|
@code{uid_t} to be @code{int} and @code{gid_t} to be @code{int}.
|
|
@end defmac
|
|
|
|
@node Generic Types, , Particular Types, Typedefs
|
|
@subsection Generic Type Checking Macros
|
|
|
|
These macros are used to find types not covered by the
|
|
particular test macros.
|
|
|
|
@defmac AC_CHECK_TYPE (@var{type}, @var{default})
|
|
@maindex CHECK_TYPE
|
|
If the type @var{type} is not defined in @file{sys/types.h}, define it
|
|
to be the C (or C++) builtin type @var{default}; e.g., @samp{short} or
|
|
@samp{unsigned}.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_SIZEOF (@var{type})
|
|
@maindex CHECK_SIZEOF
|
|
Define @code{SIZEOF_@var{uctype}} to be the size in bytes of the C (or
|
|
C++) builtin type @var{type}, e.g. @samp{int} or @samp{char *}. If
|
|
@samp{type} is unknown to the compiler, it gets a size of 0. @var{uctype}
|
|
is @var{type}, with lowercase converted to uppercase, spaces changed to
|
|
underscores, and asterisks changed to @samp{P}. For example, the call
|
|
@example
|
|
AC_CHECK_SIZEOF(int *)
|
|
@end example
|
|
@noindent
|
|
defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
|
|
@end defmac
|
|
|
|
@node Library Functions, Structures, Typedefs, Existing Tests
|
|
@section Library Functions
|
|
|
|
The following macros check for particular C library functions.
|
|
If there is no macro specifically defined to check for a function you need,
|
|
and you don't need to check for any special properties of
|
|
it, then you can use one of the general function check macros.
|
|
|
|
@menu
|
|
* Particular Functions:: Special handling to find certain functions.
|
|
* Generic Functions:: How to find other functions.
|
|
@end menu
|
|
|
|
@node Particular Functions, Generic Functions, , Library Functions
|
|
@subsection Checks For Particular Functions
|
|
|
|
These macros check for particular C functions.
|
|
|
|
@defmac AC_FUNC_ALLOCA
|
|
@maindex FUNC_ALLOCA
|
|
@cvindex C_ALLOCA
|
|
@cvindex HAVE_ALLOCA_H
|
|
@ovindex ALLOCA
|
|
Check how to get @code{alloca}. Tries to get a builtin version by
|
|
checking for @file{alloca.h} or the predefined C preprocessor macros
|
|
@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
|
|
it defines @code{HAVE_ALLOCA_H}.
|
|
|
|
If those attempts fail, it looks for the function in the standard C
|
|
library. If any of those methods succeed, it defines
|
|
@code{HAVE_ALLOCA}. Otherwise, it sets the output variable
|
|
@code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so
|
|
programs can periodically call @samp{alloca(0)} to garbage collect).
|
|
This variable is separate from @code{LIBOBJS} so multiple programs can
|
|
share the value of @code{ALLOCA} without needing to create an actual
|
|
library, in case only some of them use the code in @code{LIBOBJS}.
|
|
|
|
This macro does not try to get @code{alloca} from the System V R3
|
|
@file{libPW} or the System V R4 @file{libucb} because those libraries
|
|
contain some incompatible functions that cause trouble. Some versions
|
|
do not even contain @code{alloca} or contain a buggy version. If you
|
|
still want to use their @code{alloca}, use @code{ar} to extract
|
|
@file{alloca.o} from them instead of compiling @file{alloca.c}.
|
|
|
|
Source files that use @code{alloca} should start with a piece of code
|
|
like the following, to declare it properly. Note that in some versions
|
|
of AIX, the declaration of @code{alloca} must precede everything else
|
|
except for comments and preprocessor directives. The @code{#pragma}
|
|
directive is indented so that pre-ANSI C compilers will ignore it,
|
|
rather than choke on it.
|
|
|
|
@example
|
|
@group
|
|
/* AIX requires this to be the first thing in the file. */
|
|
#ifdef __GNUC__
|
|
# define alloca __builtin_alloca
|
|
#else
|
|
# if HAVE_ALLOCA_H
|
|
# include <alloca.h>
|
|
# else
|
|
# ifdef _AIX
|
|
#pragma alloca
|
|
# else
|
|
# ifndef alloca /* predefined by HP cc +Olibcalls */
|
|
char *alloca ();
|
|
# endif
|
|
# endif
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_CLOSEDIR_VOID
|
|
@maindex FUNC_CLOSEDIR_VOID
|
|
@cvindex CLOSEDIR_VOID
|
|
If the @code{closedir} function does not return a meaningful value,
|
|
define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
|
|
return value for an error indicator. This macro calls
|
|
@code{AC_HEADER_DIRENT} if it has not been called yet already
|
|
(@pxref{Particular Headers}).
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETLOADAVG
|
|
@maindex FUNC_GETLOADAVG
|
|
@cvindex SVR4
|
|
@cvindex DGUX
|
|
@cvindex UMAX
|
|
@cvindex UMAX4_3
|
|
@cvindex NLIST_STRUCT
|
|
@cvindex NLIST_NAME_UNION
|
|
@cvindex GETLODAVG_PRIVILEGED
|
|
@cvindex NEED_SETGID
|
|
@ovindex LIBOBJS
|
|
@ovindex NEED_SETGID
|
|
@ovindex KMEM_GROUP
|
|
Check how to get the system load averages. If the system has the
|
|
@code{getloadavg} function, this macro defines @code{HAVE_GETLOADAVG},
|
|
and adds to @code{LIBS} any libraries needed to get that function.
|
|
|
|
Otherwise, it adds @samp{getloadavg.o} to the output variable
|
|
@code{LIBOBJS}, and possibly defines several other C preprocessor
|
|
macros and output variables:
|
|
|
|
@enumerate
|
|
@item
|
|
It defines @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if
|
|
on those systems.
|
|
|
|
@item
|
|
If it finds @file{nlist.h}, it defines @code{NLIST_STRUCT}.
|
|
|
|
@item
|
|
If @samp{struct nlist} has an @samp{n_un} member, it defines
|
|
@code{NLIST_NAME_UNION}.
|
|
|
|
@item
|
|
If compiling @file{getloadavg.c} defines @code{LDAV_PRIVILEGED},
|
|
programs need to be installed specially on this system for
|
|
@code{getloadavg} to work, and this macro defines
|
|
@code{GETLOADAVG_PRIVILEGED}.
|
|
|
|
@item
|
|
This macro always defines @code{NEED_SETGID}, for @code{make}. The
|
|
value is @samp{true} if special installation is required, @samp{false}
|
|
if not. If @code{NEED_SETGID} is @samp{true}, it sets @code{KMEM_GROUP}
|
|
to the name of the group that should own the installed program.
|
|
@end enumerate
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MMAP
|
|
@maindex FUNC_MMAP
|
|
@cvindex HAVE_MMAP
|
|
If the @code{mmap} function exists and works correctly, define
|
|
@code{HAVE_MMAP}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_SETVBUF_REVERSED
|
|
@maindex FUNC_SETVBUF_REVERSED
|
|
@cvindex SETVBUF_REVERSED
|
|
If @code{setvbuf} takes the buffering type as its second argument and
|
|
the buffer pointer as the third, instead of the other way around, define
|
|
@code{SETVBUF_REVERSED}. This is the case on System V before release 3.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STRCOLL
|
|
@maindex FUNC_STRCOLL
|
|
@cvindex HAVE_STRCOLL
|
|
If the @code{strcoll} function exists and works correctly, define
|
|
@code{HAVE_STRCOLL}. This does a bit more than
|
|
@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
|
|
definitions of @code{strcoll}, which should not be used.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_UTIME_NULL
|
|
@maindex FUNC_UTIME_NULL
|
|
@cvindex HAVE_UTIME_NULL
|
|
If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
|
|
the present, define @code{HAVE_UTIME_NULL}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_VFORK
|
|
@maindex FUNC_VFORK
|
|
@cvindex HAVE_VFORK_H
|
|
@cvindex vfork
|
|
If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
|
|
@code{vfork} is not found, define @code{vfork} to be @code{fork}. This
|
|
macro checks for several known errors in implementations of @code{vfork}
|
|
and considers the system to not have a working @code{vfork} if it
|
|
detects any of them.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_VPRINTF
|
|
@maindex FUNC_VPRINTF
|
|
@cvindex HAVE_VPRINTF
|
|
@cvindex HAVE_DOPRNT
|
|
If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
|
|
@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
|
|
is available, you may assume that @code{vfprintf} and @code{vsprintf}
|
|
are also available.)
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_WAIT3
|
|
@maindex FUNC_WAIT3
|
|
@cvindex HAVE_WAIT3
|
|
If @code{wait3} is found and fills in the contents of its third argument
|
|
(a @samp{struct rusage *}), which HP-UX does not do, define
|
|
@code{HAVE_WAIT3}.
|
|
@end defmac
|
|
|
|
@node Generic Functions, , Particular Functions, Library Functions
|
|
@subsection Generic Function Checking Macros
|
|
|
|
These macros are used to find functions not covered by the particular
|
|
test macros.
|
|
|
|
@defmac AC_CHECK_FUNC (@var{function}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]})
|
|
@maindex CHECK_FUNC
|
|
If C function @var{function} is available, run shell commands
|
|
@var{action-if-found}, otherwise @var{action-if-not-found}. If the
|
|
functions might be in libraries other than the default C library, first
|
|
call @code{AC_CHECK_LIB} for those libraries. If you just want to
|
|
define a symbol if the function is available, consider using
|
|
@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
|
|
linkage even when @code{AC_LANG_CPLUSPLUS} has been called, since C++ is
|
|
more standardized than C is. (@pxref{Language Choice}, for more
|
|
information about selecting the language for checks.)
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_FUNCS (@var{function}@dots{} @r{[}, @var{action}@r{]})
|
|
@maindex CHECK_FUNCS
|
|
@cvindex HAVE_@var{function}
|
|
For each given @var{function} in the whitespace-separated argument list
|
|
that is available, define @code{HAVE_@var{function}} (in all caps).
|
|
@xref{Existing Tests}, for a precise definition of ``define'' as it
|
|
is used here. If @var{action} is given, it is additional shell code to execute
|
|
when one of the functions is found. You can give an @var{action} of
|
|
@samp{break} to break out of the loop on the first match.
|
|
If the functions might be in libraries other than the
|
|
default C library, first call @code{AC_CHECK_LIB} for those libraries.
|
|
@end defmac
|
|
|
|
@defmac AC_REPLACE_FUNCS (@var{function-name}@dots{})
|
|
@maindex REPLACE_FUNCS
|
|
@ovindex LIBOBJS
|
|
For each given @var{function-name} in the whitespace-separated argument
|
|
list that is not in the C library, add @samp{@var{function-name}.o} to
|
|
the value of the output variable @code{LIBOBJS}. If the functions
|
|
might be in libraries other than the default C library, first call
|
|
@code{AC_CHECK_LIB} for those libraries.
|
|
@end defmac
|
|
|
|
@node Structures, Compiler Characteristics, Library Functions, Existing Tests
|
|
@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
|
|
structures not listed here.
|
|
|
|
@defmac AC_HEADER_STAT
|
|
@maindex HEADER_STAT
|
|
@maindex STAT_MACROS_BROKEN
|
|
If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in
|
|
@file{sys/stat.h} do not work properly (returning false positives),
|
|
define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
|
|
Amdahl UTS and Motorola System V/88.
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_TIME
|
|
@maindex HEADER_TIME
|
|
@cvindex TIME_WITH_SYS_TIME
|
|
If a program may include both @file{time.h} and @file{sys/time.h},
|
|
define @code{TIME_WITH_SYS_TIME}. On some older systems,
|
|
@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
|
|
protected against multiple inclusion, so programs should not explicitly
|
|
include both files. This macro is useful in programs that use, for
|
|
example, @code{struct timeval} or @code{struct timezone} as well as
|
|
@code{struct tm}. It is best used in conjunction with
|
|
@code{HAVE_SYS_TIME_H}.
|
|
|
|
@example
|
|
#ifdef TIME_WITH_SYS_TIME
|
|
# include <sys/time.h>
|
|
# include <time.h>
|
|
#else
|
|
# ifdef HAVE_SYS_TIME_H
|
|
# include <sys/time.h>
|
|
# else
|
|
# include <time.h>
|
|
# endif
|
|
#endif
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_ST_BLKSIZE
|
|
@maindex STRUCT_ST_BLKSIZE
|
|
@cvindex HAVE_ST_BLKSIZE
|
|
If @code{struct stat} contains an @code{st_blksize} member, define
|
|
@code{HAVE_ST_BLKSIZE}.
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_ST_BLOCKS
|
|
@maindex STRUCT_ST_BLOCKS
|
|
@cvindex HAVE_ST_BLOCKS
|
|
@ovindex LIBOBJS
|
|
If @code{struct stat} contains an @code{st_blocks} member, define
|
|
@code{HAVE_ST_BLOCKS}. Otherwise, add @samp{fileblocks.o} to the
|
|
output variable @code{LIBOBJS}.
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_ST_RDEV
|
|
@maindex STRUCT_ST_RDEV
|
|
@cvindex HAVE_ST_RDEV
|
|
If @code{struct stat} contains an @code{st_rdev} member, define
|
|
@code{HAVE_ST_RDEV}.
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_TM
|
|
@maindex STRUCT_TM
|
|
@cvindex TM_IN_SYS_TIME
|
|
If @file{time.h} does not define @code{struct tm}, define
|
|
@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
|
|
defines @code{struct tm}.
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_TIMEZONE
|
|
@maindex STRUCT_TIMEZONE
|
|
@cvindex HAVE_TM_ZONE
|
|
@cvindex HAVE_TZNAME
|
|
Figure out how to get the current timezone. If @code{struct tm} has a
|
|
@code{tm_zone} member, define @code{HAVE_TM_ZONE}. Otherwise, if the
|
|
external array @code{tzname} is found, define @code{HAVE_TZNAME}. This
|
|
macro calls @code{AC_STRUCT_TM} if it hasn't been called already.
|
|
@end defmac
|
|
|
|
@node Compiler Characteristics, System Services, Structures, Existing Tests
|
|
@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.
|
|
|
|
@defmac AC_C_BIGENDIAN
|
|
@maindex C_BIGENDIAN
|
|
@cvindex WORDS_BIGENDIAN
|
|
If words are stored with the most significant byte first (like Motorola
|
|
and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}.
|
|
@end defmac
|
|
|
|
@defmac AC_C_CHAR_UNSIGNED
|
|
@maindex C_CHAR_UNSIGNED
|
|
@cvindex __CHAR_UNSIGNED__
|
|
If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
|
|
unless the C compiler predefines it.
|
|
@end defmac
|
|
|
|
@defmac AC_C_CONST
|
|
@maindex C_CONST
|
|
@cvindex const
|
|
If the C compiler does not fully support the keyword @code{const},
|
|
define @code{const} to be empty. Some C compilers that do not define
|
|
@code{__STDC__} do support @code{const}; some compilers that define
|
|
@code{__STDC__} do not completely support @code{const}. Programs can
|
|
simply use @code{const} as if every C compiler supported it; for those
|
|
that don't, the @file{Makefile} or configuration header file will define
|
|
it as empty. (If using a configuration header file, the program should
|
|
include it before any other header files, to prevent inconsistencies in
|
|
declarations.)
|
|
@end defmac
|
|
|
|
@defmac AC_C_CROSS
|
|
@maindex C_CROSS
|
|
If the C compiler being used does not produce executables that can run
|
|
on the system where @code{configure} is being run, set the shell
|
|
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}.
|
|
@end defmac
|
|
|
|
@defmac AC_C_INLINE
|
|
@maindex C_INLINE
|
|
@cvindex inline
|
|
If the C compiler is a version of GCC that supports the keyword
|
|
@code{__inline} but not @code{inline} (such as some NeXT versions),
|
|
define @code{inline} to be @code{__inline}. This macro calls
|
|
@code{AC_PROG_CC} if it hasn't been called already.
|
|
@end defmac
|
|
|
|
@defmac AC_INT_16_BITS
|
|
@maindex INT_16_BITS
|
|
@cvindex INT_16_BITS
|
|
If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
|
|
This macro is obsolete; it is more general to use
|
|
@samp{AC_CHECK_SIZEOF(int)} instead (@pxref{Generic Types}).
|
|
@end defmac
|
|
|
|
@defmac AC_LONG_64_BITS
|
|
@maindex LONG_64_BITS
|
|
@cvindex LONG_64_BITS
|
|
If the C type @code{long int} is 64 bits wide, define
|
|
@code{LONG_64_BITS}. This macro is obsolete; it is more general to use
|
|
@samp{AC_CHECK_SIZEOF(long)} instead (@pxref{Generic Types}).
|
|
@end defmac
|
|
|
|
@defmac AC_C_LONG_DOUBLE
|
|
@maindex C_LONG_DOUBLE
|
|
@cvindex HAVE_LONG_DOUBLE
|
|
If the C compiler supports the @code{long double} type, define
|
|
@code{HAVE_LONG_DOUBLE}. Some C compilers that do not define
|
|
@code{__STDC__} do support the @code{long double} type; some compilers
|
|
that define @code{__STDC__} do not support @code{long double}.
|
|
@end defmac
|
|
|
|
@node System Services, UNIX Variants, Compiler Characteristics, Existing Tests
|
|
@section System Services
|
|
|
|
The following macros check for operating system services or capabilities.
|
|
|
|
@defmac AC_SYS_INTERPRETER
|
|
@maindex SYS_INTERPRETER
|
|
Check whether the system supports starting shell scripts with a line of
|
|
the form @samp{#!/bin/csh} to select the shell to use. After running
|
|
this macro, shell code in @code{configure.in} can check the variable
|
|
@code{ac_cv_sys_interpreter}; it will be set to @samp{yes} if the system
|
|
supports @samp{#!}, @samp{no} if not.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_X
|
|
@maindex PATH_X
|
|
Try to locate the X Window System include files and libraries. If the
|
|
user gave the command line options @samp{--x-includes=@var{dir}} and
|
|
@samp{--x-libraries=@var{dir}}, use those directories. If either or
|
|
both were not given, get the missing values by running @code{xmkmf} on a
|
|
trivial @file{Imakefile} and examining the @file{Makefile} that it
|
|
produces. If that fails (such as if @code{xmkmf} is not present), look
|
|
for them in several directories where they often reside. If either
|
|
method is successful, set the shell variables @code{x_includes} and
|
|
@code{x_libraries} to their locations, unless they are in directories
|
|
the compiler searches by default.
|
|
|
|
If both methods fail, or the user gave the command line option
|
|
@samp{--without-x}, set the shell variable @code{no_x} to @samp{yes};
|
|
otherwise set it to the empty string.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_XTRA
|
|
@maindex PATH_XTRA
|
|
@ovindex X_CFLAGS
|
|
@ovindex X_LIBS
|
|
@ovindex X_EXTRA_LIBS
|
|
An enhanced version of @code{AC_PATH_X}. Put the C compiler flags that
|
|
X needs into output variable @code{X_CFLAGS}, and the X linker
|
|
flags into @code{X_LIBS}. If X is not available, put
|
|
@samp{-DX_DISPLAY_MISSING} into @code{X_CFLAGS}.
|
|
|
|
Also check for special libraries that some systems need in order to
|
|
compile X programs. Add any that the system needs to output
|
|
variable @code{X_EXTRA_LIBS}. This macro calls @code{AC_PATH_X} and
|
|
@code{AC_OS_ISC} (@pxref{UNIX Variants}) if they have not already
|
|
been called. Because of the macro dependencies, if you call this macro,
|
|
you should let it call @code{AC_PATH_X} rather than doing that yourself.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_LONG_FILE_NAMES
|
|
@maindex SYS_LONG_FILE_NAMES
|
|
@cvindex HAVE_LONG_FILE_NAMES
|
|
If the system supports file names longer than 14 characters, define
|
|
@code{HAVE_LONG_FILE_NAMES}.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_RESTARTABLE_SYSCALLS
|
|
@maindex SYS_RESTARTABLE_SYSCALLS
|
|
@cvindex HAVE_RESTARTABLE_SYSCALLS
|
|
If the system automatically restarts a system call that is interrupted
|
|
by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}.
|
|
@end defmac
|
|
|
|
@node UNIX Variants, , System Services, Existing Tests
|
|
@section UNIX Variants
|
|
|
|
The following macros check for certain operating systems that need
|
|
special treatment for some programs, due to exceptional oddities in
|
|
their header files or libraries. These macros are warts; they should
|
|
be replaced by a more systematic approach, based either on the
|
|
functions they make available or the environments they provide.
|
|
|
|
@defmac AC_OS_AIX
|
|
@maindex OS_AIX
|
|
@cvindex _ALL_SOURCE
|
|
If on AIX, define @code{_ALL_SOURCE}. Allows the use of some BSD
|
|
functions. Should be called before any macros that run the C compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_OS_DYNIX
|
|
@maindex OS_DYNIX
|
|
If on DYNIX/ptx (Sequent UNIX), add @samp{-lseq} to output
|
|
variable @code{LIBS}. Allows use of some BSD system calls and
|
|
@code{getmntent}.
|
|
@end defmac
|
|
|
|
@defmac AC_OS_IRIX
|
|
@maindex OS_IRIX
|
|
If on IRIX (Silicon Graphics UNIX), add @samp{-lsun} to output
|
|
variable @code{LIBS}. Needed to get @code{getmntent}. At sites using
|
|
Yellow Pages/NIS, it is also needed to get properly working
|
|
@code{gethostby*}, @code{getpw*}, @code{getgr*}, @code{getnetby*}, and
|
|
so on.
|
|
@c (According to Garrett.Wollman@uvm.edu.)
|
|
@end defmac
|
|
|
|
@defmac AC_OS_ISC
|
|
@maindex OS_ISC
|
|
@cvindex _POSIX_SOURCE
|
|
@ovindex CC
|
|
If on a POSIXized ISC UNIX, define @code{_POSIX_SOURCE} and add
|
|
@samp{-posix} (for the GNU C compiler) or @samp{-Xp} (for other C
|
|
compilers) to output variable @code{CC}. This allows the use of
|
|
POSIX facilities. Must be called after @code{AC_PROG_CC} and before
|
|
any other macros that run the C compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_OS_MINIX
|
|
@maindex OS_MINIX
|
|
@cvindex _MINIX
|
|
@cvindex _POSIX_SOURCE
|
|
@cvindex _POSIX_1_SOURCE
|
|
If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
|
|
@code{_POSIX_1_SOURCE} to be 2. This allows the use of POSIX
|
|
facilities. Should be called before any macros that run the C compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_OS_SCO
|
|
@maindex OS_SCO
|
|
@ovindex LIBS
|
|
If on SCO UNIX, add @samp{-lintl} to output variable @code{LIBS}.
|
|
Used to get @code{strftime}. It must be called before checking for
|
|
@code{strftime}.
|
|
@end defmac
|
|
|
|
@defmac AC_OS_XENIX
|
|
@maindex OS_XENIX
|
|
@ovindex LIBS
|
|
If on Xenix, add @samp{-lx} to output variable @code{LIBS}. Also,
|
|
if @file{sys/ndir.h} is not being used, add @samp{-ldir} to @code{LIBS}.
|
|
Needed when using the directory reading functions. This macro calls
|
|
@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
|
|
|
|
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.
|
|
|
|
@menu
|
|
* C System Output:: Checking output of the C compiler system.
|
|
* 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
|
|
|
|
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
|
|
Values}), because they don't know enough about the information they are
|
|
checking for to generate a cache variable name. They also do not print
|
|
any messages, for the same reason. The checks for particular kinds of C
|
|
features call these macros and do cache their results and print messages
|
|
about what they're checking for.
|
|
|
|
@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
|
|
prints @samp{checking for @var{echo-text}} to the standard output first,
|
|
if @var{echo-text} is non-empty.
|
|
@end defmac
|
|
|
|
@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]})
|
|
@maindex EGREP_CPP
|
|
@var{program} is the text of a C or C++ program, on which shell
|
|
variable, backquote, and backslash substitutions are performed. If the
|
|
output of running the preprocessor on @var{program} contains the
|
|
@code{egrep} regular expression @var{pattern}, execute shell commands
|
|
@var{action-if-found}, otherwise execute @var{action-if-not-found}.
|
|
|
|
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.
|
|
@end defmac
|
|
|
|
@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]})
|
|
@maindex EGREP_HEADER
|
|
If the output of running the preprocessor on the system header file
|
|
@var{header-file} contains the @code{egrep} regular expression
|
|
@var{pattern}, execute shell commands @var{action-if-found}, otherwise
|
|
execute @var{action-if-not-found}.
|
|
|
|
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.
|
|
@var{action-if-not-found}.
|
|
|
|
You can not check whether preprocessor symbols are defined this way,
|
|
because they get expanded before @code{egrep} sees them. But you can
|
|
almost always detect them by simply using @code{#ifdef} directives in
|
|
your programs.
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_CPP (@var{includes}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]})
|
|
@maindex TRY_CPP
|
|
@var{includes} is C or C++ @code{#include} statements and declarations,
|
|
on which shell variable, backquote, and backslash substitutions are
|
|
performed. (Actually, it can be any C program, but other statements are
|
|
probably not useful.) If the preprocessor produces no error messages
|
|
while processing it, run shell commands @var{action-if-true}. Otherwise
|
|
run shell commands @var{action-if-false}.
|
|
|
|
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. It uses @code{CPPFLAGS}, but not @code{CFLAGS},
|
|
because @samp{-g}, @samp{-O}, etc. are not valid options to many C
|
|
preprocessors.
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]})
|
|
@maindex TRY_LINK
|
|
Create a test C program to see whether a function whose body consists of
|
|
@var{function-body} can be compiled and linked; @var{includes} is any
|
|
@code{#include} statements needed by the code in @var{function-body}.
|
|
If the file compiles and links successfully, run shell commands
|
|
@var{action-if-found}, otherwise run @var{action-if-not-found}. This
|
|
macro uses @code{CFLAGS} or @code{CXXFLAGS}, @code{CPPFLAGS},
|
|
@code{LDFLAGS}, and @code{LIBS} when compiling.
|
|
|
|
A few systems have linkers that do not return a failure exit status when
|
|
there are unresolved functions in the link. This bug makes the
|
|
configuration scripts produced by Autoconf unusable on those systems.
|
|
However, some of them can be given options that make the exit status
|
|
correct. This is a problem that Autoconf does not currently address.
|
|
@end defmac
|
|
|
|
@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
|
|
backquote substitutions are performed. If it compiles and links
|
|
successfully and returns an exit status of 0 when executed, run shell
|
|
commands @var{action-if-true}. Otherwise run shell commands
|
|
@var{action-if-false}; the exit status of the program is available in
|
|
the shell variable @samp{$?}. This macro uses @code{CFLAGS} or
|
|
@code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS} when
|
|
compiling.
|
|
|
|
If the C compiler being used does not produce executables that run on
|
|
the system where @code{configure} is being run, then the test program is
|
|
not run. If the optional shell commands @var{action-if-cross-compiling}
|
|
are given, they are run instead and this macro calls @code{AC_C_CROSS}
|
|
if it has not already been called (@pxref{Compiler Characteristics}).
|
|
Otherwise, @code{configure} prints an error message and exits.
|
|
@code{autoconf} prints a warning message when creating @code{configure}
|
|
each time it encounters a call to @code{AC_TRY_RUN} with no
|
|
@var{action-if-cross-compiling} argument given. You may ignore the
|
|
warning, though users will not be able to configure your package for
|
|
cross-compiling. A few of the macros distributed with Autoconf produce
|
|
this warning message.
|
|
|
|
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
|
|
|
|
These macros help other macros to define variables that are used in the
|
|
@code{configure} shell script and substituted into output files.
|
|
|
|
@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.
|
|
|
|
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}.
|
|
|
|
If @code{AC_CONFIG_HEADER} has been called, then instead of substituting
|
|
@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
|
|
correct values into @code{#define} statements in a template file.
|
|
@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:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf")
|
|
@end example
|
|
|
|
@noindent
|
|
or this:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(elf.h,
|
|
AC_DEFINE(SVR4)
|
|
LIBS="$LIBS -lelf")
|
|
@end example
|
|
|
|
@noindent
|
|
instead of this:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf")
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_DEFINE_UNQUOTED (@var{variable} @r{[}, @var{value}@r{]})
|
|
@maindex DEFINE_UNQUOTED
|
|
Like @code{AC_DEFINE}, but three shell expansions are performed---once---on
|
|
@var{value}: variable expansion (@samp{$}), command substitution
|
|
(@samp{`}), and backslash escaping (@samp{\}). Use this macro instead
|
|
of @code{AC_DEFINE} when @var{value} is a shell variable. For
|
|
example:
|
|
|
|
@example
|
|
AC_DEFINE_UNQUOTED(config_machfile, "$@{machfile@}")
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_SUBST (@var{variable})
|
|
@maindex SUBST
|
|
Substitute the variable @var{variable} when creating the output files
|
|
(typically one or more @file{Makefile}s). This means replace instances
|
|
of @samp{@@@var{variable}@@}, e.g. in @file{Makefile.in}, with the
|
|
current value of the shell variable @var{variable}. The value of
|
|
@var{variable} should not contain literal newlines. If this macro were
|
|
not called, the value of @var{variable} would not be set in the output
|
|
files, even though @code{configure} had figured out a value for it.
|
|
|
|
You can set or add to the value of @var{variable} in the usual shell
|
|
way. For example, to add @samp{-ltermcap} to the value of the variable
|
|
@code{LIBS}:
|
|
|
|
@example
|
|
LIBS="$LIBS -ltermcap"
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_SUBST_FILE (@var{variable})
|
|
@maindex SUBST_FILE
|
|
Substitute the contents of the file named by shell variable
|
|
@var{variable} into output variable @var{variable} when
|
|
creating the output files (typically one or more @file{Makefile}s).
|
|
This macro is useful for inserting @file{Makefile} fragments containing
|
|
special dependencies or other @code{make} directives for particular host
|
|
or target types into @file{Makefile}s.
|
|
|
|
For example, @file{configure.in} could contain:
|
|
|
|
@example
|
|
AC_SUBST_FILE(host_frag)dnl
|
|
host_frag=$srcdir/conf/sun4.mh
|
|
@end example
|
|
|
|
@noindent
|
|
and then a @file{Makefile.in} could contain:
|
|
|
|
@example
|
|
@@host_frag@@
|
|
@end example
|
|
@end defmac
|
|
|
|
@node Printing Messages, Language Choice, Setting Variables, Primitives
|
|
@section Printing Messages
|
|
|
|
@code{configure} scripts need to give users running them several kinds
|
|
of information. The following macros print messages in ways appropriate
|
|
for different kinds of information. The arguments to all of them get
|
|
enclosed in shell double quotes, so the shell performs variable and
|
|
backquote substitution on them.
|
|
|
|
These macros are all wrappers around the @code{echo} shell command.
|
|
Other macros should rarely need to run @code{echo} directly to print
|
|
messages for the @code{configure} user. Using these macros makes it
|
|
easy to change how and when each kind of message is printed; such
|
|
changes need only be made to the macro definitions, and all of the
|
|
callers change automatically.
|
|
|
|
@defmac AC_CHECKING (@var{feature-description})
|
|
@maindex CHECKING
|
|
This macro is similar to @code{AC_MSG_CHECKING}, except that it prints a
|
|
newline after the @var{feature-description}. It is useful mainly to
|
|
print a general description of the overall purpose of a group of feature
|
|
checks, e.g.
|
|
|
|
@example
|
|
AC_CHECKING(if stack overflow is detectable)
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_CHECKING (@var{feature-description})
|
|
@maindex MSG_CHECKING
|
|
Notify the user that @code{configure} is checking for a particular
|
|
feature. This macro prints a message that starts with @samp{checking }
|
|
and ends with @samp{...} and no newline. It must be followed by a call
|
|
to @code{AC_MSG_RESULT} to print the result of the check and the
|
|
newline. The @var{feature-description} should be something like
|
|
@samp{whether the Fortran compiler accepts C++ comments} or @samp{for
|
|
c89}.
|
|
|
|
This macro prints nothing if @code{configure} is run with the
|
|
@samp{--quiet} or @samp{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_ERROR (@var{error-description})
|
|
@maindex MSG_ERROR
|
|
Notify the user of an error that prevents @code{configure} from
|
|
completing. This macro prints an error message on the standard error
|
|
stream and exits @code{configure} with a nonzero status.
|
|
@var{error-description} should be something like @samp{invalid value
|
|
$HOME for \$HOME}.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_RESULT (@var{result-description})
|
|
@maindex MSG_RESULT
|
|
Notify the user of the results of a check. @var{result-description} is
|
|
almost always the value of the cache variable for the check, typically
|
|
@samp{yes}, @samp{no}, or a file name. This macro should follow a call
|
|
to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
|
|
the completion of the message printed by the call to
|
|
@code{AC_MSG_CHECKING}.
|
|
|
|
This macro prints nothing if @code{configure} is run with the
|
|
@samp{--quiet} or @samp{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_WARN (@var{problem-description})
|
|
@maindex MSG_WARN
|
|
Notify the @code{configure} user of a possible problem. This macro
|
|
prints the message on the standard error stream; @code{configure}
|
|
continues running afterward, so macros that call @code{AC_MSG_WARN} should
|
|
provide a default (back-up) behavior for the situations they warn about.
|
|
@var{problem-description} should be something like @samp{ln -s seems to
|
|
make hard links}.
|
|
@end defmac
|
|
|
|
@defmac AC_VERBOSE (@var{result-description})
|
|
@maindex VERBOSE
|
|
This macro is similar to @code{AC_MSG_RESULT}, except that it is meant
|
|
to follow a call to @code{AC_CHECKING} instead of
|
|
@code{AC_MSG_CHECKING}; it starts the message it prints with a tab. It
|
|
is considered obsolete.
|
|
@end defmac
|
|
|
|
@node Language Choice, , Printing Messages, Primitives
|
|
@section Language Choice
|
|
|
|
Packages that use both C and C++ need to test features of both
|
|
compilers. Autoconf-generated @code{configure} scripts check for C
|
|
features by default. The following macros determine which language's
|
|
compiler is used in tests that follow in @file{configure.in}.
|
|
|
|
@defmac AC_LANG_C
|
|
@maindex LANG_C
|
|
Do compilation tests using @code{CC} and @code{CPP} and use extension
|
|
@file{.c} for test programs.
|
|
|
|
This is the initial state.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_CPLUSPLUS
|
|
@maindex LANG_CPLUSPLUS
|
|
Do compilation tests using @code{CXX} and @code{CXXCPP} and use
|
|
extension @file{.C} for test programs.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_RESTORE
|
|
@maindex LANG_RESTORE
|
|
Select the language that is saved on the top of the stack, as set by
|
|
@code{AC_LANG_SAVE}, and remove it from the stack. This macro is
|
|
equivalent to either @code{AC_LANG_C} or @code{AC_LANG_CPLUSPLUS},
|
|
whichever had been run most recently when @code{AC_LANG_SAVE} was last
|
|
called.
|
|
|
|
Do not call this macro more times than @code{AC_LANG_SAVE}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_SAVE
|
|
@maindex LANG_SAVE
|
|
Remember the current language (as set by @code{AC_LANG_C} or
|
|
@code{AC_LANG_CPLUSPLUS}) on a stack. Does not change which language is
|
|
current. Use this macro and @code{AC_LANG_RESTORE} in macros that need
|
|
to temporarily switch to a particular language.
|
|
@end defmac
|
|
|
|
@defmac AC_REQUIRE_CPP
|
|
@maindex REQUIRE_CPP
|
|
Ensure that whichever preprocessor would currently be used for tests has
|
|
been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
|
|
argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
|
|
depending on which language is current.
|
|
@end defmac
|
|
|
|
@node Writing Macros, Caching Values, Primitives, 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.
|
|
|
|
If you add macros that you think would be useful to other people, or
|
|
find problems with the distributed macros, please send electronic mail
|
|
to @file{bug-gnu-utils@@prep.ai.mit.edu}, so we can consider them for
|
|
future releases of Autoconf. Please include the Autoconf version
|
|
number, which you can get by running @samp{autoconf --version}.
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Macro Format, Macro Naming, , Writing Macros
|
|
@section Macro Format
|
|
|
|
@maindex DEFUN
|
|
Autoconf macros are defined as arguments to the @code{AC_DEFUN} macro,
|
|
which is similar to the @code{m4} builtin @code{define} macro. In
|
|
addition to defining the macro, @code{AC_DEFUN} adds some code to the
|
|
macro which is used to constrain the order in which macros are called
|
|
(@pxref{Prerequisite Macros}).
|
|
|
|
An Autoconf macro definition looks like this:
|
|
|
|
@example
|
|
AC_DEFUN(@var{macro-name}, [@var{macro-body}])
|
|
@end example
|
|
|
|
@noindent
|
|
The square brackets here do not indicate optional text: they should
|
|
literally be present in the macro definition to avoid macro expansion
|
|
problems (@pxref{Quoting}). You can refer to any arguments passed to
|
|
the macro as @samp{$1}, @samp{$2}, etc.
|
|
|
|
The @code{m4} builtin @code{dnl} is used to introduce comments in
|
|
@code{m4}; it causes @code{m4} to discard the text through the next
|
|
newline. It is not needed between macro definitions in @file{acsite.m4}
|
|
and @file{aclocal.m4}, because all output is discarded until
|
|
@code{AC_INIT} is called.
|
|
|
|
@xref{Definitions, , How to define new macros, m4.info, GNU m4}, for
|
|
more complete information on writing @code{m4} macros.
|
|
|
|
@node Macro Naming, Quoting, Macro Format, Writing Macros
|
|
@section Macro Naming
|
|
|
|
All of the Autoconf macros have all-uppercase names starting with
|
|
@samp{AC_} to prevent them from accidentally conflicting with other
|
|
text. All shell variables that they use for internal purposes have
|
|
mostly-lowercase names starting with @samp{ac_}. To ensure that your
|
|
macros don't conflict with present or future Autoconf macros, you should
|
|
prefix your own macro names and any shell variables they use with some
|
|
other sequence. Possibilities include your initials, or an abbreviation
|
|
for the name of your organization or software package.
|
|
|
|
Most of the Autoconf macros' names follow a structured naming convention
|
|
that indicates the kind of feature check by the name. The macro names
|
|
consist of several words, separated by underscores, going from most
|
|
general to most specific. The names of their cache variables use the
|
|
same convention (@pxref{Cache Variables}, for more information on them).
|
|
|
|
The first word of the name after @samp{AC_} usually tells the category
|
|
of feature being tested. Here are the categories used in Autoconf for
|
|
specific test macros, the kind of macro that you are more likely to
|
|
write. They are also used for cache variables, in all-lowercase. Use
|
|
them where applicable; where they're not, invent your own categories.
|
|
|
|
@table @code
|
|
@item C
|
|
C language builtin features.
|
|
@item DECL
|
|
Declarations of C variables in header files.
|
|
@item FUNC
|
|
Functions in libraries.
|
|
@item GROUP
|
|
UNIX group owners of files.
|
|
@item HEADER
|
|
Header files.
|
|
@item LIB
|
|
C libraries.
|
|
@item OS
|
|
Quirks of particular operating systems.
|
|
@item PATH
|
|
The full path names to files, including programs.
|
|
@item PROG
|
|
The base names of programs.
|
|
@item STRUCT
|
|
Definitions of C structures in header files.
|
|
@item SYS
|
|
Operating system features.
|
|
@item TYPE
|
|
C builtin or declared types.
|
|
@item VAR
|
|
C variables in libraries.
|
|
@end table
|
|
|
|
After the category comes the name of the particular feature being
|
|
tested. Any further words in the macro name indicate particular aspects
|
|
of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
|
|
behavior of the @code{utime} function when called with a @code{NULL}
|
|
pointer.
|
|
|
|
A macro that is an internal subroutine of another macro should have a
|
|
name that starts with the name of that other macro, followed by one or
|
|
more words saying what the internal macro does. For example,
|
|
@code{AC_PATH_X} has internal macros @code{AC_PATH_X_XMKMF} and
|
|
@code{AC_PATH_X_DIRECT}.
|
|
|
|
@node Quoting, Dependencies Between Macros, Macro Naming, Writing Macros
|
|
@section Quoting
|
|
|
|
Macros that are called by other macros are evaluated by @code{m4}
|
|
several times; each evaluation might require another layer of quotes to
|
|
prevent unwanted expansions of macros or @code{m4} builtins, such as
|
|
@samp{define} and @samp{$1}. Quotes are also required around macro
|
|
arguments that contain commas, since commas separate the arguments from
|
|
each other. It's a good idea to quote any macro arguments that contain
|
|
newlines or calls to other macros, as well.
|
|
|
|
Autoconf changes the @code{m4} quote characters
|
|
from the default @samp{`} and @samp{'} to @samp{[} and @samp{]}, because
|
|
many of the macros use @samp{`} and @samp{'}, mismatched. However, in a
|
|
few places the macros need to use brackets (usually in C program text or
|
|
regular expressions). In those places, they use the @code{m4} builtin
|
|
command @code{changequote} to temporarily change the quote characters to
|
|
@samp{<<} and @samp{>>}. (Sometimes, if they don't need to quote
|
|
anything, they disable quoting entirely instead by setting the quote
|
|
characters to empty strings.) Here is an example:
|
|
|
|
@example
|
|
AC_TRY_LINK(
|
|
changequote(<<, >>)dnl
|
|
<<#include <time.h>
|
|
#ifndef tzname /* For SGI. */
|
|
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
|
|
#endif>>,
|
|
changequote([, ])dnl
|
|
[atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
|
|
@end example
|
|
|
|
When you create a @code{configure} script using newly written macros,
|
|
examine it carefully to check whether you need to add more quotes in
|
|
your macros. If one or more words have disappeared in the @code{m4}
|
|
output, you need more quotes. When in doubt, quote.
|
|
|
|
However, it's also possible to put on too many layers of quotes. If
|
|
this happens, the resulting @code{configure} script will contain
|
|
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
|
|
@section Dependencies Between Macros
|
|
|
|
Some Autoconf macros depend on other macros having been called first in
|
|
order to work correctly. Autoconf provides a way to ensure that certain
|
|
macros are called if needed and a way to warn the user if macros are
|
|
called in an order that might cause incorrect operation.
|
|
|
|
@menu
|
|
* Prerequisite Macros:: Ensuring required information.
|
|
* Suggested Ordering:: Warning about possible ordering problems.
|
|
* Obsolete Macros:: Warning about old ways of doing things.
|
|
@end menu
|
|
|
|
@node Prerequisite Macros, Suggested Ordering, , Dependencies Between Macros
|
|
@subsection Prerequisite Macros
|
|
|
|
A macro that you write might need to use values that have previously
|
|
been computed by other macros. For example, @code{AC_DECL_YYTEXT}
|
|
examines the output of @code{flex} or @code{lex}, so it depends on
|
|
@code{AC_PROG_LEX} having been called first to set the shell variable
|
|
@code{LEX}.
|
|
|
|
Rather than forcing the user of the macros to keep track of the
|
|
dependencies between them, you can use the @code{AC_REQUIRE} macro to do
|
|
it automatically. @code{AC_REQUIRE} can ensure that a macro is only
|
|
called if it is needed, and only called once.
|
|
|
|
@defmac AC_REQUIRE (@var{macro-name})
|
|
@maindex REQUIRE
|
|
If the @code{m4} macro @var{macro-name} has not already been called,
|
|
call it (without any arguments). Make sure to quote @var{macro-name}
|
|
with square brackets. @var{macro-name} must have been defined using
|
|
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
|
|
that it has been called.
|
|
@end defmac
|
|
|
|
An obsolete alternative to using @code{AC_DEFUN} is to use @code{define}
|
|
and call @code{AC_PROVIDE}:
|
|
|
|
@defmac AC_PROVIDE (@var{macro-name})
|
|
@maindex PROVIDE
|
|
Set a flag recording that @var{macro-name} has been called.
|
|
@var{macro-name} should be the name of the macro that is calling
|
|
@code{AC_PROVIDE}. An easy way to get it is from the @code{m4} builtin
|
|
variable @code{$0}, like this:
|
|
|
|
@example
|
|
AC_PROVIDE([$0])
|
|
@end example
|
|
@end defmac
|
|
|
|
@node Suggested Ordering, Obsolete Macros, Prerequisite Macros, Dependencies Between Macros
|
|
@subsection Suggested Ordering
|
|
|
|
Some macros should be run before another macro if both are called, but
|
|
neither @emph{requires} that the other be called. For example, a macro
|
|
like @code{AC_OS_AIX} that changes the behavior of the C compiler
|
|
(@pxref{UNIX Variants}) should be called before any macros that run the
|
|
C compiler. Many of these dependencies are noted in the documentation.
|
|
|
|
Autoconf provides a way to warn users when macros with this kind of
|
|
dependency appear out of order in a @file{configure.in} file. The
|
|
warning occurs when creating @file{configure} from @file{configure.in},
|
|
not when running @file{configure}.
|
|
The @code{AC_BEFORE} macro causes @code{m4} to print a warning message
|
|
on the standard error output when a macro is used before another macro
|
|
which might change its behavior. The macro which should come first
|
|
should contain a call to @code{AC_BEFORE}.
|
|
|
|
For example, @code{AC_OS_AIX} contains
|
|
|
|
@example
|
|
AC_BEFORE([$0], [AC_TRY_LINK])
|
|
@end example
|
|
|
|
@noindent
|
|
As a result, if @code{AC_OS_AIX} is called after @code{AC_TRY_LINK},
|
|
it will note that @code{AC_TRY_LINK} has already been called and
|
|
print a warning message.
|
|
|
|
@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
|
|
@maindex BEFORE
|
|
Make @code{m4} print a warning message on the standard error output if
|
|
@var{called-macro-name} has already been called. @var{this-macro-name}
|
|
should be the name of the macro that is calling @code{AC_BEFORE}. The
|
|
macro @var{called-macro-name} must have been defined using
|
|
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
|
|
that it has been called.
|
|
|
|
This macro should be used when one macro makes changes that might affect
|
|
another macro, so that the other macro should probably not be called
|
|
first. For example, @code{AC_PROG_CPP} checks whether the C compiler
|
|
can run the C preprocessor when given the @samp{-E} option. It should
|
|
therefore be called after any macros that change which C compiler is
|
|
being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
|
|
|
|
@example
|
|
AC_BEFORE([$0], [AC_PROG_CPP])dnl
|
|
@end example
|
|
|
|
@noindent
|
|
This warns the user if a call to @code{AC_PROG_CPP} has already occurred
|
|
when @code{AC_PROG_CC} is called.
|
|
@end defmac
|
|
|
|
@node Obsolete Macros, , Suggested Ordering, Dependencies Between Macros
|
|
@subsection Obsolete Macros
|
|
|
|
Configuration and portability technology has evolved over the years.
|
|
Often better ways of solving a particular problem are developed, or
|
|
ad-hoc approaches are systematized. This process has occurred in many
|
|
parts of Autoconf. One result is that some of the macros are now
|
|
considered @dfn{obsolete}; they still work, but are no longer considered
|
|
the best thing to do. Autoconf has a way to warn users producing
|
|
@code{configure} scripts when they use obsolete macros, to encourage
|
|
them to modernize.
|
|
|
|
@defmac AC_OBSOLETE (@var{this-macro-name} @r{[}, @var{suggestion}@r{]})
|
|
@maindex OBSOLETE
|
|
Make @code{m4} print a message on the standard error output warning that
|
|
@var{this-macro-name} is obsolete, and giving the file and line number
|
|
where it was called. @var{this-macro-name} should be the name of the
|
|
macro that is calling @code{AC_BEFORE}. If @var{suggestion} is given,
|
|
it is printed at the end of the warning message; for example, it can be
|
|
a suggestion for what to use instead of @var{this-macro-name}.
|
|
|
|
A sample call is:
|
|
|
|
@example
|
|
AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])
|
|
@end example
|
|
@end defmac
|
|
|
|
@node Portable Shell, Checking for Files, Dependencies Between Macros, Writing Macros
|
|
@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 found in all shells!
|
|
|
|
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
|
|
|
|
@node Cache Files, Cache Variables, , Caching Values
|
|
@section Cache Files
|
|
|
|
A cache file is a shell script that caches the results of configure
|
|
tests run on one system so they can be shared between configure scripts
|
|
and configure runs. It is not useful on other systems. If its contents
|
|
are invalid for some reason, the user may delete or edit it.
|
|
|
|
By default, configure uses @file{./config.cache} as the cache file,
|
|
creating it if it does not exist already. @code{configure} accepts the
|
|
@samp{--cache-file=@var{file}} option to use a different cache file;
|
|
that is what @code{configure} does when it calls @code{configure}
|
|
scripts in subdirectories, so they share the cache. Giving
|
|
@samp{--cache-file=/dev/null} disables caching, for debugging
|
|
@code{configure}. @xref{Output}, for information on configuring
|
|
subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
|
|
@file{config.status} only pays attention to the cache file if it is
|
|
given the @samp{--recheck} option, which makes it rerun
|
|
@code{configure}.
|
|
|
|
It is wrong to try to distribute cache files for particular system types.
|
|
There is too much room for error in doing that, and too much
|
|
administrative overhead in maintaining them. For any features that
|
|
can't be guessed automatically, use the standard method of the canonical
|
|
system type and linking files (@pxref{Manual Configuration}).
|
|
|
|
The cache file on a particular system will gradually accumulate whenever
|
|
someone runs a @code{configure} script; it will be initially
|
|
nonexistent. Running @code{configure} merges the new cache results with
|
|
the existing cache file. The site initialization script can specify a
|
|
site-wide cache file to use instead of the default, to make it work
|
|
transparently, as long as the same C compiler is used every time
|
|
(@pxref{Site Default Values}).
|
|
|
|
@node Cache Variables, , Cache Files, Caching Values
|
|
@section Cache Variables
|
|
|
|
The names of cache variables should have the following format:
|
|
|
|
@example
|
|
@var{package-prefix}_cv_@var{value-type}_@var{specific-value}@r{[}_@var{additional-options}@r{]}
|
|
@end example
|
|
|
|
@noindent
|
|
for example, @samp{ac_cv_header_stat_broken} or
|
|
@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
|
|
|
|
@table @asis
|
|
@item @var{package-prefix}
|
|
An abbreviation for your package or organization; the same prefix you
|
|
begin local Autoconf macros with, except lowercase by convention.
|
|
For cache values used by the distributed Autoconf macros, this value is
|
|
@samp{ac}.
|
|
|
|
@item @code{_cv_}
|
|
Indicates that this shell variable is a cache value.
|
|
|
|
@item @var{value-type}
|
|
A convention for classifying cache values, to produce a rational naming
|
|
system. The values used in Autoconf are listed in @ref{Macro Naming}.
|
|
|
|
@item @var{specific-value}
|
|
Which member of the class of cache values this test applies to.
|
|
For example, which function (@samp{alloca}), program (@samp{gcc}), or
|
|
output variable (@samp{INSTALL}).
|
|
|
|
@item @var{additional-options}
|
|
Any particular behavior of the specific member that this test applies to.
|
|
For example, @samp{broken} or @samp{set}. This part of the name may
|
|
be omitted if it does not apply.
|
|
@end table
|
|
|
|
Like their names, the values the may be assigned to cache variables have
|
|
a few restrictions. The values may not contain single quotes or curly braces.
|
|
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
|
|
@chapter Manual Configuration
|
|
|
|
Some kinds of features can't be guessed automatically by running test
|
|
programs. For example, how to allocate a pseudo tty, or the details of
|
|
the object file format, or special options that need to be passed to the
|
|
compiler or linker to provide a POSIX or ANSI C environment. It is
|
|
possible to check for such features using ad-hoc means, such as having
|
|
@code{configure} check the output of the @code{uname} program, or
|
|
looking for libraries that are unique to particular systems. However,
|
|
Autoconf provides a uniform method for handling unguessable features.
|
|
|
|
@menu
|
|
* Specifying Names:: Specifying the system type.
|
|
* Canonicalizing:: Getting the canonical system type.
|
|
* System Name Variables:: Variables containing the system type.
|
|
* Using System Type:: What to do with the system type.
|
|
@end menu
|
|
|
|
@node Specifying Names, Canonicalizing, , Manual Configuration
|
|
@section Specifying the System Type
|
|
|
|
Like other GNU @code{configure} scripts, Autoconf-generated
|
|
@code{configure} scripts can make decisions based on a canonical name
|
|
for the system type, which has the form:
|
|
|
|
@example
|
|
@var{cpu}-@var{company}-@var{system}
|
|
@end example
|
|
|
|
@code{configure} can usually guess the canonical name for the type of
|
|
system it's running on. To do so it runs a script called
|
|
@code{config.guess}, which derives the name using the @code{uname}
|
|
command or symbols predefined by the C preprocessor.
|
|
|
|
Alternately, the user can specify the system type with command line
|
|
arguments to @code{configure}. Doing so is necessary when
|
|
cross-compiling. In the most complex case of cross-compiling, three
|
|
system types are involved. The options to specify them are:
|
|
|
|
@table @code
|
|
@item --build=@var{build-type}
|
|
the type of system on which the package is being configured and
|
|
compiled (rarely needed);
|
|
|
|
@item --host=@var{host-type}
|
|
the type of system on which the package will run;
|
|
|
|
@item --target=@var{target-type}
|
|
the type of system for which any compiler tools in the package will
|
|
produce code.
|
|
@end table
|
|
|
|
@noindent
|
|
If the user gives @code{configure} a non-option argument, it is used as
|
|
the default for the host, target, and build system types if the user
|
|
does not specify them explicitly with options. The target and build
|
|
types default to the host type if it is given and they are not. Note
|
|
that if you are cross-compiling, you still have to specify the names of
|
|
the cross-tools you use, in particular the C compiler, on the
|
|
@code{configure} and @code{make} command lines, e.g.,
|
|
|
|
@example
|
|
CC=m68k-coff-gcc configure --target=m68k-coff; CC=m68k-coff-gcc make
|
|
@end example
|
|
|
|
@code{configure} recognizes short aliases for many system types; for
|
|
example, @samp{decstation} can be given on the command line instead of
|
|
@samp{mips-dec-ultrix4.2}. @code{configure} runs a script called
|
|
@code{config.sub} to canonicalize system type aliases.
|
|
|
|
@node Canonicalizing, System Name Variables, Specifying Names, Manual Configuration
|
|
@section Getting the Canonical System Type
|
|
|
|
The following macros make the name of the system type available in
|
|
@code{configure} scripts.
|
|
|
|
@defmac AC_CANONICAL_HOST
|
|
@maindex CANONICAL_HOST
|
|
Perform only the subset of @code{AC_CANONICAL_SYSTEM} relevant to the
|
|
host type. This is all that is needed for programs that are not part of
|
|
a compiler toolchain.
|
|
@end defmac
|
|
|
|
@defmac AC_CANONICAL_SYSTEM
|
|
@maindex CANONICAL_SYSTEM
|
|
Set shell and output variables to the names of the canonical system
|
|
types. If the user did not specify one or more of those values on the
|
|
command line, run @code{config.guess} to determine them. Run
|
|
@code{config.sub} to canonicalize any aliases the user gave. If you use
|
|
this macro, you must distribute those two shell scripts along with your
|
|
source code (@pxref{Output}, for information about the
|
|
@code{AC_CONFIG_AUX_DIR} macro which you can use to control which
|
|
directory @code{configure} looks for those scripts in). If you do not
|
|
run this macro, @code{configure} ignores any @samp{--host}, etc. options
|
|
given to it.
|
|
@end defmac
|
|
|
|
@node System Name Variables, Using System Type, Canonicalizing, Manual Configuration
|
|
@section System Name Variables
|
|
|
|
After calling @code{AC_CANONICAL_SYSTEM} or @code{AC_CANONICAL_HOST},
|
|
the shell and output variables that contain the system type
|
|
information are:
|
|
|
|
@table @code
|
|
@ovindex build
|
|
@ovindex host
|
|
@ovindex target
|
|
@item @code{build}, @code{host}, @code{target}
|
|
the canonical system names;
|
|
|
|
@item @code{build_alias}, @code{host_alias}, @code{target_alias}
|
|
@ovindex build_alias
|
|
@ovindex host_alias
|
|
@ovindex target_alias
|
|
the names the user specified, or the canonical names if
|
|
@code{config.guess} was used;
|
|
|
|
@item @code{build_cpu}, @code{build_vendor}, @code{build_os}
|
|
@itemx @code{host_cpu}, @code{host_vendor}, @code{host_os}
|
|
@itemx @code{target_cpu}, @code{target_vendor}, @code{target_os}
|
|
@ovindex build_cpu
|
|
@ovindex host_cpu
|
|
@ovindex target_cpu
|
|
@ovindex build_vendor
|
|
@ovindex host_vendor
|
|
@ovindex target_vendor
|
|
@ovindex build_os
|
|
@ovindex host_os
|
|
@ovindex target_os
|
|
the individual parts of the canonical names (for convenience).
|
|
@end table
|
|
|
|
@node Using System Type, , System Name Variables, Manual Configuration
|
|
@section Using the System Type
|
|
|
|
How do you use a canonical system type? Usually, you use it in one or
|
|
more @code{case} statements in @file{configure.in} to select
|
|
system-specific C files. Then link those files, which have names based
|
|
on the system name, to generic names, such as @file{host.h} or
|
|
@file{target.c}. The @code{case} statement patterns can use shell
|
|
wildcards to group several cases together, like in this fragment:
|
|
|
|
@example
|
|
case "$target" in
|
|
i386-*-mach* | i386-*-gnu*) obj_format=aout emulation=mach bfd_gas=yes ;;
|
|
i960-*-bout) obj_format=bout ;;
|
|
esac
|
|
@end example
|
|
|
|
@defmac AC_LINK_FILES (@var{dest} @dots{}, @var{source} @dots{})
|
|
@maindex LINK_FILES
|
|
Link each of the existing files @var{source} to the corresponding link
|
|
name @var{dest}. Makes a symbolic link if possible, otherwise a hard
|
|
link. For example, this call:
|
|
|
|
@example
|
|
AC_LINK_FILES(config/sun3.h config/aout.h, host.h object.h)
|
|
@end example
|
|
|
|
@noindent
|
|
creates in the current directory @file{host.h}, which is a link to
|
|
@file{@var{srcdir}/config/sun3.h}, and @file{object.h}, which is a link
|
|
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
|
|
@chapter Running @code{configure} Scripts
|
|
|
|
A software package that uses a @code{configure} script
|
|
should be distributed with a file @file{Makefile.in}, but no
|
|
@file{Makefile}; that way, the user has to properly configure the
|
|
package for the local system before compiling it.
|
|
Below are instructions on how to configure a package that uses a
|
|
@code{configure} script, suitable for inclusion as an @file{INSTALL}
|
|
file in the package.
|
|
|
|
@menu
|
|
* Basic Installation:: Instructions for typical cases.
|
|
* Compilers and Options:: Selecting compilers and optimization.
|
|
* Build Directory:: Configuring in a different directory.
|
|
* Installation Names:: Installing in different directories.
|
|
* System Type:: Specifying the system type.
|
|
* Optional Features:: Selecting optional features.
|
|
@end menu
|
|
|
|
@include install.texi
|
|
|
|
@node Invoking config.status, Site Default Values, Invoking configure, Top
|
|
@chapter Recreating a Configuration
|
|
|
|
The @code{configure} script creates a file named @file{config.status}
|
|
which describes which configuration options were specified when the
|
|
package was last configured. This file is a shell script which,
|
|
if run, will recreate the same configuration.
|
|
|
|
You can give @file{config.status} the @samp{--recheck} option to update
|
|
itself. This option is useful if you change @code{configure}, so that
|
|
the results of some tests might be different from the previous run. The
|
|
@samp{--recheck} option re-runs @code{configure} with the same arguments
|
|
you used before, plus the @samp{--no-create} option, which prevent
|
|
@code{configure} from running @file{config.status} and creating
|
|
@file{Makefile} and other files, and the @samp{--no-recursion} option,
|
|
which prevents @code{configure} from running other @code{configure}
|
|
scripts in subdirectories. (This is so other @file{Makefile} rules can
|
|
run @file{config.status} when it changes; @pxref{Automatic Remaking},
|
|
for an example).
|
|
|
|
@file{config.status} also accepts the options @samp{--help}, which
|
|
prints a summary of the options to @file{config.status}, and
|
|
@samp{--version}, which prints the version of Autoconf used to create
|
|
the @code{configure} script that generated @file{config.status}.
|
|
|
|
@file{config.status} checks several optional environment variables that
|
|
can alter its behavior:
|
|
|
|
@defvar CONFIG_SHELL
|
|
@evindex CONFIG_SHELL
|
|
The shell with which to run @code{configure} for the @samp{--recheck}
|
|
option. The default is @file{/bin/sh}.
|
|
@end defvar
|
|
|
|
@defvar CONFIG_STATUS
|
|
@evindex CONFIG_STATUS
|
|
The file name to use for the shell script that records the
|
|
configuration. The default is @file{./config.status}. This variable is
|
|
useful when one package uses parts of another and the @file{configure}
|
|
scripts shouldn't be merged because they are maintained separately.
|
|
@end defvar
|
|
|
|
The following variables provide one way for separately distributed
|
|
packages to share the values computed by @code{configure}. Doing so can
|
|
be useful if some of the packages need a superset of the features that
|
|
one of them, perhaps a common library, does. These variables allow a
|
|
@file{config.status} file to create files other than the ones that its
|
|
@file{configure.in} specifies, so it can be used for a different package.
|
|
|
|
@defvar CONFIG_FILES
|
|
@evindex CONFIG_FILES
|
|
The files in which to perform @samp{@@@var{variable}@@} substitutions.
|
|
The default is the arguments given to @code{AC_OUTPUT} in @file{configure.in}.
|
|
@end defvar
|
|
|
|
@defvar CONFIG_HEADERS
|
|
@evindex CONFIG_HEADERS
|
|
The files in which to substitute C @code{#define} statements.
|
|
The default is the arguments given to @code{AC_CONFIG_HEADER}; if that
|
|
macro was not called, @file{config.status} ignores this variable.
|
|
@end defvar
|
|
|
|
These variables also allow you to write @file{Makefile} rules that
|
|
regenerate only some of the files. For example, in the dependencies
|
|
given above (@pxref{Automatic Remaking}), @file{config.status} is run
|
|
twice when @file{configure.in} has changed. If that bothers you, you
|
|
can make each run only regenerate the files for that rule:
|
|
|
|
@example
|
|
@group
|
|
# config.status might not change config.h
|
|
config.h: stamp-h
|
|
stamp-h: config.h.in config.status
|
|
CONFIG_FILES= CONFIG_HEADERS=config.h ./config.status
|
|
touch stamp-h
|
|
|
|
Makefile: Makefile.in config.status
|
|
CONFIG_FILES=Makefile CONFIG_HEADERS= ./config.status
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(If @file{configure.in} does not call @code{AC_CONFIG_HEADER}, there is
|
|
no need to set @code{CONFIG_HEADERS} in the @code{make} rules.)
|
|
|
|
@node Site Default Values, Concerns, Invoking config.status, Top
|
|
@chapter Site Default Values
|
|
|
|
Autoconf-generated @code{configure} scripts support site and system wide
|
|
initialization files. You can create these files to provide default
|
|
values for some configuration values, both on all of your systems and
|
|
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.
|
|
|
|
Site files can be arbitrary shell scripts, but only certain kinds of
|
|
code are really appropriate to be in them. Besides selecting a cache
|
|
file, they are good places to set default values for other shell
|
|
variables like @code{CC}, if you need to give them unusual values:
|
|
anything you would normally do, repetitively, on the command line. If
|
|
you use non-default values for @var{prefix} or @var{exec_prefix}
|
|
(wherever you locate the site file), you can set them in the site file
|
|
if you specify it with the @code{CONFIG_SITE} environment variable.
|
|
|
|
It is possible to set some cache values in the site file.
|
|
If you are cross-compiling, it is impossible to check features that
|
|
require running a test program. You could ``prime the cache'' by
|
|
setting those values correctly for that system in
|
|
@file{@var{exec_prefix}/lib/config.site}. The cache file is careful to
|
|
not override any variables set in the site files. Similarly, you should
|
|
not override command-line options in the site files. Your code should
|
|
check that variables such as @code{prefix} and @code{cache_file} have
|
|
their default values (as set near the top of @code{configure}) before
|
|
changing them.
|
|
|
|
Here is a sample file @file{/usr/share/local/gnu/lib/config.site}.
|
|
@samp{configure --prefix=/usr/share/local/gnu} would read this file.
|
|
|
|
@example
|
|
# config.site for configure
|
|
#
|
|
# Give Autoconf 2.x generated configure scripts a shared default
|
|
# 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.
|
|
test $exec_prefix = NONE && exec_prefix=/usr/local/gnu
|
|
@end example
|
|
|
|
@node Concerns, Upgrading, Site Default Values, Top
|
|
@chapter Concerns About Autoconf
|
|
|
|
Several concerns about Autoconf come up regularly. Here some of them
|
|
are addressed.
|
|
|
|
@menu
|
|
* Copyright:: Legal restrictions on Autoconf output.
|
|
* Why GNU m4:: Why not use the standard @code{m4}?
|
|
* Bootstrapping:: Autoconf and GNU @code{m4} require each other?
|
|
* Policy Decisions:: Configuring site policy.
|
|
@end menu
|
|
|
|
@node Copyright, Why GNU m4, , Concerns
|
|
@section Copyright on @code{configure} Scripts
|
|
|
|
@display
|
|
What are the restrictions on distributing @code{configure}
|
|
scripts that Autoconf generated? How does that affect my
|
|
programs that use them?
|
|
@end display
|
|
|
|
The configuration scripts that Autoconf produces are covered by the GNU
|
|
General Public License. This is because they consist almost entirely of
|
|
parts of Autoconf itself, rearranged somewhat, and Autoconf is
|
|
distributed under the terms of the GPL. As applied to Autoconf, the GPL
|
|
just means that you need to distribute @file{configure.in}, and
|
|
@file{acsite.m4}, @file{aclocal.m4}, @file{acconfig.h}, and
|
|
@file{@var{config}.h.top} and @file{@var{config}.h.bot} if you use them,
|
|
along with @file{configure}.
|
|
|
|
Programs that use Autoconf scripts to configure themselves do not
|
|
automatically come under the GPL. Distributing an Autoconf
|
|
configuration script as part of a program is considered to be @emph{mere
|
|
aggregation} of that work with the Autoconf script. Such programs are
|
|
not derivative works based on Autoconf; only their configuration scripts
|
|
are. We still encourage software authors to distribute their work under
|
|
terms like those of the GPL, but doing so is not required to use
|
|
Autoconf.
|
|
|
|
@node Why GNU m4, Bootstrapping, Copyright, Concerns
|
|
@section Why Require GNU @code{m4}?
|
|
|
|
@display
|
|
Why does Autoconf require GNU @code{m4}?
|
|
@end display
|
|
|
|
Many @code{m4} implementations have hard-coded limitations on the size
|
|
and number of macros, which Autoconf exceeds. They also lack several
|
|
builtin macros that it would be difficult to get along without in a
|
|
sophisticated application like Autoconf, including:
|
|
|
|
@example
|
|
builtin
|
|
indir
|
|
patsubst
|
|
__file__
|
|
__line__
|
|
@end example
|
|
|
|
Since only software maintainers need to use Autoconf, and since GNU
|
|
@code{m4} is simple to configure and install, it does not seem like an
|
|
unreasonable burden to require GNU @code{m4} to be installed also. Most
|
|
maintainers of GNU and other free software already have most of the GNU
|
|
utilities installed, since they prefer them.
|
|
|
|
@node Bootstrapping, Policy Decisions, Why GNU m4, Concerns
|
|
@section How Can I Bootstrap?
|
|
|
|
@display
|
|
If Autoconf requires GNU @code{m4} and GNU @code{m4} has an
|
|
Autoconf @code{configure} script, how do I bootstrap? It seems
|
|
like a chicken and egg problem!
|
|
@end display
|
|
|
|
Although GNU @code{m4} does come with a @code{configure} script produced
|
|
by Autoconf, Autoconf is @emph{not} required in order to run the script
|
|
and install GNU @code{m4}. Autoconf is only required if you want to
|
|
@emph{change} the @code{m4} @code{configure} script, which few people
|
|
have to do (mainly its maintainer).
|
|
|
|
@node Policy Decisions, , Bootstrapping, Concerns
|
|
@section Configuring Site Policy
|
|
|
|
@display
|
|
How do I configure in policy decisions, since the
|
|
@code{configure} scripts aren't interactive?
|
|
@end display
|
|
|
|
There are two ways to do it. Simple decisions can be specified using
|
|
@samp{--with} and @samp{--enable} options to @code{configure}
|
|
(@pxref{Package Options}).
|
|
|
|
More sophisticated site configuration information---company names, email
|
|
addresses to contact, etc.---should be put in a file that is edited
|
|
@emph{only by users}. The programs should examine that file at run
|
|
time, rather than at compile time. That approach is more convenient for
|
|
users and makes the configuration process simpler than asking for the
|
|
information while configuring.
|
|
|
|
@node Upgrading, History, Concerns, Top
|
|
@chapter Upgrading From Version 1
|
|
|
|
Autoconf version 2 is mostly backward compatible with version 1.
|
|
However, it introduces better ways to do some things, and doesn't
|
|
support some of the ugly things in version 1. So, depending on how
|
|
sophisticated your @file{configure.in} files are, you might have to do
|
|
some manual work in order to upgrade to version 2. This chapter points
|
|
out some problems to watch for when upgrading. Also, perhaps your
|
|
@code{configure} scripts could benefit from some of the new features in
|
|
version 2.
|
|
|
|
First, make sure you have GNU @code{m4} version 1.1 or higher installed,
|
|
preferably 1.3 or higher. Versions before 1.1 have bugs that prevent
|
|
them from working with Autoconf version 2. Versions 1.3 and later are
|
|
much faster than earlier versions, because as of version 1.3, GNU
|
|
@code{m4} has a more efficient implementation of diversions and can
|
|
freeze its internal state in a file that it can read back quickly.
|
|
|
|
@menu
|
|
* Changed File Names:: Files you might rename.
|
|
* Changed Makefiles:: New things to put in @file{Makefile.in}.
|
|
* Changed Macros:: Macro calls you might replace.
|
|
* Changed Results:: Changes in how to check test results.
|
|
* Changed Macro Writing:: Better ways to write your own macros.
|
|
@end menu
|
|
|
|
@node Changed File Names, Changed Makefiles, , Upgrading
|
|
@section Changed File Names
|
|
|
|
If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
|
|
in a particular package's source directory), you must rename it to
|
|
@file{acsite.m4}. @xref{Invoking autoconf}.
|
|
|
|
If you were using @file{config.h.top} or @file{config.h.bot}, you still
|
|
can, but you will have less clutter if you merge them into
|
|
@file{acconfig.h}. @xref{Invoking autoheader}.
|
|
|
|
@node Changed Makefiles, Changed Macros, Changed File Names, Upgrading
|
|
@section Changed Makefiles
|
|
|
|
Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
|
|
your @file{Makefile.in} files, so they can take advantage of the values
|
|
of those variables in the environment when @code{configure} is run.
|
|
Doing this isn't necessary, but it's a convenience for users.
|
|
|
|
If you have the following in @file{Makefile.in}:
|
|
|
|
@example
|
|
prefix = /usr/local
|
|
exec_prefix = $@{prefix@}
|
|
@end example
|
|
|
|
@noindent
|
|
you must change it to:
|
|
|
|
@example
|
|
prefix = @@prefix@@
|
|
exec_prefix = @@exec_prefix@@
|
|
@end example
|
|
|
|
@noindent
|
|
The old feature of replacing those variables without @samp{@@}
|
|
characters around them has been removed.
|
|
|
|
@node Changed Macros, Changed Results, Changed Makefiles, Upgrading
|
|
@section Changed Macros
|
|
|
|
Many of the macros were renamed in Autoconf version 2. You can still
|
|
use the old names, but the new ones are clearer, and it's easier to find
|
|
the documentation for them. @xref{Old Macro Names}, for a table showing
|
|
the new names for the old macros. Use the @code{autoupdate} program to
|
|
convert your @file{configure.in} to using the new macro names.
|
|
@xref{Invoking autoupdate}.
|
|
|
|
Some macros have been superseded by similar ones that do the job better,
|
|
but are not call-compatible. If you get warnings about calling obsolete
|
|
macros while running @code{autoconf}, you may safely ignore them, but your
|
|
@code{configure} script will generally work better if you follow the
|
|
advice it prints about what to replace the obsolete macros with. In
|
|
particular, the mechanism for reporting the results of tests has
|
|
changed. If you were using @code{echo} or @code{AC_VERBOSE}, your
|
|
@code{configure} script's output will look better if you switch to
|
|
@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT}. @xref{Printing
|
|
Messages}. Those macros work best in conjunction with cache variables.
|
|
@xref{Caching Values}.
|
|
|
|
@node Changed Results, Changed Macro Writing, Changed Macros, Upgrading
|
|
@section Changed Results
|
|
|
|
If you were checking the results of previous tests by examining the
|
|
shell variable @code{DEFS}, you need to switch to checking the values of
|
|
the cache variables for those tests. @code{DEFS} no longer exists while
|
|
@code{configure} is running; it is only created when generating output
|
|
files. This difference from version 1 is because properly quoting the
|
|
contents of that variable turned out to be too cumbersome and
|
|
inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
|
|
Variables}.
|
|
|
|
For example, here is a @file{configure.in} fragment written for Autoconf
|
|
version 1:
|
|
|
|
@example
|
|
AC_HAVE_FUNCS(syslog)
|
|
case "$DEFS" in
|
|
*-DHAVE_SYSLOG*) ;;
|
|
*) # syslog is not in the default libraries. See if it's in some other.
|
|
saved_LIBS="$LIBS"
|
|
for lib in bsd socket inet; do
|
|
AC_CHECKING(for syslog in -l$lib)
|
|
LIBS="$saved_LIBS -l$lib"
|
|
AC_HAVE_FUNCS(syslog)
|
|
case "$DEFS" in
|
|
*-DHAVE_SYSLOG*) break ;;
|
|
*) ;;
|
|
esac
|
|
LIBS="$saved_LIBS"
|
|
done ;;
|
|
esac
|
|
@end example
|
|
|
|
Here is a way to write it for version 2:
|
|
|
|
@example
|
|
AC_CHECK_FUNCS(syslog)
|
|
if test $ac_cv_func_syslog = no; then
|
|
# syslog is not in the default libraries. See if it's in some other.
|
|
for lib in bsd socket inet; do
|
|
AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
|
|
LIBS="$LIBS $lib"; break])
|
|
done
|
|
fi
|
|
@end example
|
|
|
|
If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
|
|
backslashes before quotes, you need to remove them. It now works
|
|
predictably, and does not treat quotes (except backquotes) specially.
|
|
@xref{Setting Variables}.
|
|
|
|
@node Changed Macro Writing, , Changed Results, Upgrading
|
|
@section Changed Macro Writing
|
|
|
|
When defining your own macros, you should now use @code{AC_DEFUN}
|
|
instead of @code{define}. @code{AC_DEFUN} automatically calls
|
|
@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
|
|
do not interrupt other macros, to prevent nested @samp{checking@dots{}}
|
|
messages on the screen. There's no actual harm in continuing to use the
|
|
older way, but it's less convenient and attractive. @xref{Macro
|
|
Format}.
|
|
|
|
You probably looked at the macros that came with Autoconf as a guide for
|
|
how to do things. It would be a good idea to take a look at the new
|
|
versions of them, as the style is somewhat improved and they take
|
|
advantage of some new features.
|
|
|
|
If you were doing tricky things with undocumented Autoconf internals
|
|
(diversions, macros, variables), check whether you need to change
|
|
anything to account for changes that have been made. Perhaps you can
|
|
even use an officially supported technique in version 2 instead of
|
|
kludging. Or perhaps not.
|
|
|
|
To speed up your locally written feature tests, add caching to them. If
|
|
you don't encapsulate your tests into macros, do so; don't be sloppy.
|
|
(I've been guilty myself.) @xref{Caching Values}.
|
|
|
|
@node History, Old Macro Names, Upgrading, Top
|
|
@chapter History of Autoconf
|
|
|
|
You may be wondering, Why was Autoconf originally written? How did it
|
|
get into its present form? (Why does it look like gorilla spit?) If
|
|
you're not wondering, then this chapter contains no information useful
|
|
to you, and you might as well skip it. If you @emph{are} wondering,
|
|
then let there be light@dots{}
|
|
|
|
@menu
|
|
* Genesis:: Prehistory and naming of @code{configure}.
|
|
* Exodus:: The plagues of @code{m4} and Perl.
|
|
* Leviticus:: The priestly code of portability arrives.
|
|
* Numbers:: Growth and contributors.
|
|
* Deuteronomy:: Approaching the promises of easy configuration.
|
|
@end menu
|
|
|
|
@node Genesis, Exodus, , History
|
|
@section Genesis
|
|
|
|
In June 1991 I was maintaining many of the GNU utilities for the Free
|
|
Software Foundation. As they were ported to more platforms and more
|
|
programs were added, the number of @samp{-D} options that users had to
|
|
select in the @file{Makefile} (around 20) became burdensome. Especially
|
|
for me---I had to test each new release on a bunch of different systems.
|
|
So I wrote a little shell script to guess some of the correct settings
|
|
for the fileutils package, and released it as part of fileutils 2.0.
|
|
That @code{configure} script worked well enough that the next month I
|
|
adapted it (by hand) to create similar @code{configure} scripts for
|
|
several other GNU utilities packages. Brian Berliner also adapted one
|
|
of my scripts for his CVS revision control system.
|
|
|
|
Later that summer, I learned that Richard Stallman and Richard Pixley
|
|
were developing similar scripts to use in the GNU compiler tools; so I
|
|
adapted my @code{configure} scripts to support their evolving interface:
|
|
using the file name @file{Makefile.in} as the templates; adding
|
|
@samp{+srcdir}, the first option (of many); and creating
|
|
@file{config.status} files.
|
|
|
|
@node Exodus, Leviticus, Genesis, History
|
|
@section Exodus
|
|
|
|
As I got feedback from users, I incorporated many improvements, using
|
|
Emacs to search and replace, cut and paste, similar changes in each of
|
|
the scripts. As I adapted more GNU utilities packages to use
|
|
@code{configure} scripts, updating them all by hand became impractical.
|
|
Rich Murphey, the maintainer of the GNU graphics utilities, sent me mail
|
|
saying that the @code{configure} scripts were great, and asking if I had
|
|
a tool for generating them that I could send him. No, I thought, but
|
|
I should! So I started to work out how to generate them. And the
|
|
journey from the slavery of hand-written @file{configure} scripts to the
|
|
freedom of Autoconf began.
|
|
|
|
Cygnus @code{configure}, which was being developed at around that time,
|
|
is table driven; it is meant to deal mainly with a discrete number of
|
|
system types with a small number of mainly unguessable features (such as
|
|
details of the object file format). The automatic configuration system
|
|
that Brian Fox had developed for Bash takes a similar approach. For
|
|
general use, it seems to me a hopeless cause to try to maintain an up to
|
|
date database of which features each variant of each operating system
|
|
has. It's easier and more reliable to check for most features on the
|
|
fly---especially on hybrid systems that people have hacked on locally.
|
|
|
|
I considered using an architecture similar to that of Cygnus
|
|
@code{configure}, where there is a single @code{configure} script that
|
|
reads pieces of @file{configure.in} when run. But I didn't want to have
|
|
to distribute all of the feature tests with every package, so I settled
|
|
on having a different @code{configure} made from each
|
|
@file{configure.in} by a preprocessor. That approach also offered more
|
|
control and flexibility.
|
|
|
|
I looked briefly into using Larry Wall's Metaconfig program, but I
|
|
decided not to for several reasons. The @code{Configure} scripts it
|
|
produces are interactive, which I find quite inconvenient; I didn't like
|
|
the ways it checked for some features (such as library functions); it
|
|
was not being maintained at that time, and its scripts didn't work on
|
|
many modern systems (such as System V R4 and NeXT); it wasn't very
|
|
flexible in what it could do in response to a feature's presence or
|
|
absence; I found it confusing to learn; and it was too big and complex
|
|
for my needs (I didn't realize then how much Autoconf would eventually
|
|
have to grow).
|
|
|
|
I considered using Perl to generate my style of @code{configure} scripts,
|
|
but decided that @code{m4} was better suited to the job of simple
|
|
textual substitutions: it gets in the way less, because output is
|
|
implicit. Plus, everyone already has it. (Initially I didn't rely on
|
|
the GNU extensions to @code{m4}.) Also, some of my friends at the
|
|
University of Maryland had recently been putting @code{m4} front ends on
|
|
several programs, including @code{tvtwm}, and I was interested in trying
|
|
out a new language.
|
|
|
|
@node Leviticus, Numbers, Exodus, History
|
|
@section Leviticus
|
|
|
|
Since my @code{configure} scripts determine the system's capabilities
|
|
automatically, with no interactive user intervention, I decided to call
|
|
the program that generates them Autoconfig. But with a version number
|
|
tacked on, that name would be too long for old UNIX file systems, so
|
|
I shortened it to Autoconf.
|
|
|
|
In the fall of 1991 I called together a group of priests of portability
|
|
(er, alpha testers) to give me feedback as I encapsulated pieces of my
|
|
handwritten scripts in @code{m4} macros and continued to add features
|
|
and improve the techniques used in the checks. Prominent among the
|
|
testers were
|
|
@ifinfo
|
|
Franc,ois
|
|
@end ifinfo
|
|
@tex
|
|
Fran\c cois
|
|
@end tex
|
|
Pinard, who came up with the idea of making an @file{autoconf} shell
|
|
script to run @code{m4} and check for unresolved macro calls; Karl
|
|
Berry, who championed standardizing the @code{HAVE_@var{feature}} form
|
|
for C preprocessor symbols; Rich Pixley, who suggested running the
|
|
compiler instead of searching the file system to find include files and
|
|
symbols, for more accurate results; and Ian Taylor, who added support
|
|
for creating a C header file as an alternative to putting @samp{-D}
|
|
options in a @file{Makefile}, so he could use Autoconf in his UUCP
|
|
package. The alpha testers cheerfully adjusted their files again and
|
|
again as the names and calling conventions of the Autoconf macros
|
|
changed from release to release. They all contributed many specific
|
|
checks, great ideas, and bug fixes.
|
|
|
|
@node Numbers, Deuteronomy, Leviticus, History
|
|
@section Numbers
|
|
|
|
In July 1992, after months of alpha testing, I released Autoconf 1.0,
|
|
and converted many GNU packages to use it. I was surprised by how
|
|
positive the reaction to it was. More people started using it than I
|
|
could keep track of, including people working on software that wasn't
|
|
part of the GNU Project (such as TCL, FSP, @TeX{}, and Kerberos v5).
|
|
Autoconf continued to improve rapidly, as many people using the
|
|
@code{configure} scripts reported problems they encountered.
|
|
|
|
Autoconf turned out to be a good torture test for @code{m4}
|
|
implementations. UNIX @code{m4} started to dump core because of the
|
|
length of the macros that Autoconf defined, and several bugs showed up
|
|
in GNU @code{m4} as well. Eventually, we realized that we needed to use
|
|
some features that only GNU @code{m4} has. 4.3BSD @code{m4}, in
|
|
particular, has an impoverished set of builtin macros; the System V
|
|
version is better, but still doesn't provide everything we need.
|
|
|
|
More development occurred as people put Autoconf under more stresses
|
|
(and to uses I hadn't anticipated). Karl Berry added checks for X11.
|
|
david zuhn contributed C++ support.
|
|
@ifinfo
|
|
Franc,ois
|
|
@end ifinfo
|
|
@tex
|
|
Fran\c cois
|
|
@end tex
|
|
Pinard made it diagnose invalid arguments. Jim Blandy bravely coerced
|
|
it into configuring GNU Emacs, laying the groundwork for several later
|
|
improvements. Roland McGrath got it to configure the GNU C Library,
|
|
wrote the @code{autoheader} script to automate the creation of C header
|
|
file templates, and added a @samp{--verbose} option to @code{configure}.
|
|
Noah Friedman added the @samp{--macrodir} option and @code{AC_MACRODIR}
|
|
environment variable. Roland and Noah improved the quoting protection
|
|
in @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
|
|
dealing with portability problems from February through June, 1993.
|
|
|
|
@node Deuteronomy, , Numbers, History
|
|
@section Deuteronomy
|
|
|
|
A long wish list for major features had accumulated, and the effect of
|
|
several years of patching by various people had left some residual
|
|
cruft. In April 1994, while working for Cygnus Support, I began a major
|
|
revision of Autoconf. I added most of the features of the Cygnus
|
|
@code{configure} that Autoconf had lacked, largely by adapting the
|
|
relevant parts of Cygnus @code{configure} with the help of david zuhn
|
|
and Ken Raeburn. These features include support for using
|
|
@file{config.sub}, @file{config.guess}, @samp{--host}, and
|
|
@samp{--target}; making links to files; and running @code{configure}
|
|
scripts in subdirectories. Adding these features enabled Ken to convert
|
|
GNU @code{as}, and Rob Savoye to convert DejaGNU, to using Autoconf.
|
|
|
|
I added more features in response to other peoples' requests. Many
|
|
people had asked for @code{configure} scripts to share the results of
|
|
the checks between runs, because (particularly when configuring a large
|
|
source tree, like Cygnus does) they were frustratingly slow. Mike
|
|
Haertel suggested adding site-specific initialization scripts. People
|
|
distributing software that had to unpack on MS-DOS asked for a way to
|
|
override the @file{.in} extension on the file names, which produced file
|
|
names like @file{config.h.in} containing two dots. Jim Avera did an
|
|
extensive examination of the problems with quoting in @code{AC_DEFINE}
|
|
and @code{AC_SUBST}; his insights led to significant improvements.
|
|
Richard Stallman asked that compiler output be sent to @file{config.log}
|
|
instead of @file{/dev/null}, to help people debug the Emacs
|
|
@code{configure} script.
|
|
|
|
I made some other changes because of my dissatisfaction with the quality
|
|
of the program. I made the messages showing results of the checks less
|
|
ambiguous, always printing a result. I regularized the names of the
|
|
macros and cleaned up coding style inconsistencies. I added some
|
|
auxiliary utilities that I had developed to help convert source code
|
|
packages to use Autoconf. With the help of
|
|
@ifinfo
|
|
Franc,ois
|
|
@end ifinfo
|
|
@tex
|
|
Fran\c cois
|
|
@end tex
|
|
Pinard, I made the macros not interrupt each others' messages.
|
|
(That feature revealed some performance bottlenecks in GNU @code{m4},
|
|
which he hastily rewrote!)
|
|
And I began a testsuite, because experience
|
|
had shown that Autoconf has a pronounced tendency to regress when we
|
|
change it.
|
|
|
|
Again, several alpha testers gave invaluable feedback, especially
|
|
@ifinfo
|
|
Franc,ois
|
|
@end ifinfo
|
|
@tex
|
|
Fran\c cois
|
|
@end tex
|
|
Pinard, Jim Meyering, Karl Berry, Rob Savoye, and Ken Raeburn.
|
|
|
|
Finally, version 2.0 was ready. And there was much rejoicing.
|
|
(And I have free time again. I think.)
|
|
|
|
@node Old Macro Names, Environment Variable Index, History, Top
|
|
@chapter Old Macro Names
|
|
|
|
In version 2 of Autoconf, most of the macros were renamed to use a more
|
|
uniform and descriptive naming scheme. Here are the old names of the
|
|
macros that were renamed, followed by the current names of those macros.
|
|
Although the old names are still accepted by the @code{autoconf} program
|
|
for backward compatibility, the old names are considered obsolete.
|
|
@xref{Macro Naming}, for a description of the new naming scheme.
|
|
|
|
@table @code
|
|
@item AC_AIX
|
|
@maindex AIX
|
|
@code{AC_OS_AIX}
|
|
@item AC_ALLOCA
|
|
@maindex ALLOCA
|
|
@code{AC_FUNC_ALLOCA}
|
|
@item AC_ARG_ARRAY
|
|
@maindex ARG_ARRAY
|
|
removed because of limited usefulness
|
|
@item AC_CHAR_UNSIGNED
|
|
@maindex CHAR_UNSIGNED
|
|
@code{AC_C_CHAR_UNSIGNED}
|
|
@item AC_CONST
|
|
@maindex CONST
|
|
@code{AC_C_CONST}
|
|
@item AC_CROSS_CHECK
|
|
@maindex CROSS_CHECK
|
|
@code{AC_C_CROSS}
|
|
@item AC_DYNIX_SEQ
|
|
@maindex DYNIX_SEQ
|
|
@code{AC_OS_DYNIX}
|
|
@item AC_ERROR
|
|
@maindex ERROR
|
|
@code{AC_MSG_ERROR}
|
|
@item AC_FIND_X
|
|
@maindex FIND_X
|
|
@code{AC_PATH_X}
|
|
@item AC_FIND_XTRA
|
|
@maindex FIND_XTRA
|
|
@code{AC_PATH_XTRA}
|
|
@item AC_FUNC_CHECK
|
|
@maindex FUNC_CHECK
|
|
@code{AC_CHECK_FUNC}
|
|
@item AC_GCC_TRADITIONAL
|
|
@maindex GCC_TRADITIONAL
|
|
@code{AC_PROG_GCC_TRADITIONAL}
|
|
@item AC_GETGROUPS_T
|
|
@maindex GETGROUPS_T
|
|
@code{AC_TYPE_GETGROUPS}
|
|
@item AC_GETLOADAVG
|
|
@maindex GETLOADAVG
|
|
@code{AC_FUNC_GETLOADAVG}
|
|
@item AC_HAVE_FUNCS
|
|
@maindex HAVE_FUNCS
|
|
@code{AC_CHECK_FUNCS}
|
|
@item AC_HAVE_HEADERS
|
|
@maindex HAVE_HEADERS
|
|
@code{AC_CHECK_HEADERS}
|
|
@item AC_HAVE_POUNDBANG
|
|
@maindex HAVE_POUNDBANG
|
|
@code{AC_SYS_INTERPRETER} (different calling convention)
|
|
@item AC_HEADER_CHECK
|
|
@maindex HEADER_CHECK
|
|
@code{AC_CHECK_HEADER}
|
|
@item AC_HEADER_EGREP
|
|
@maindex HEADER_EGREP
|
|
@code{AC_EGREP_HEADER}
|
|
@item AC_INLINE
|
|
@maindex INLINE
|
|
@code{AC_C_INLINE}
|
|
@item AC_IRIX_SUN
|
|
@maindex IRIX_SUN
|
|
@code{AC_OS_IRIX}
|
|
@item AC_ISC_POSIX
|
|
@maindex ISC_POSIX
|
|
@code{AC_OS_ISC}
|
|
@item AC_LN_S
|
|
@maindex LN_S
|
|
@code{AC_PROG_LN_S}
|
|
@item AC_LONG_DOUBLE
|
|
@maindex LONG_DOUBLE
|
|
@code{AC_C_LONG_DOUBLE}
|
|
@item AC_LONG_FILE_NAMES
|
|
@maindex LONG_FILE_NAMES
|
|
@code{AC_SYS_LONG_FILE_NAMES}
|
|
@item AC_MAJOR_HEADER
|
|
@maindex MAJOR_HEADER
|
|
@code{AC_HEADER_MAJOR}
|
|
@item AC_MINIX
|
|
@maindex MINIX
|
|
@code{AC_OS_MINIX}
|
|
@item AC_MINUS_C_MINUS_O
|
|
@maindex MINUS_C_MINUS_O
|
|
@code{AC_PROG_CC_C_O}
|
|
@item AC_MMAP
|
|
@maindex MMAP
|
|
@code{AC_FUNC_MMAP}
|
|
@item AC_MODE_T
|
|
@maindex MODE_T
|
|
@code{AC_TYPE_MODE_T}
|
|
@item AC_OFF_T
|
|
@maindex OFF_T
|
|
@code{AC_TYPE_OFF_T}
|
|
@item AC_PID_T
|
|
@maindex PID_T
|
|
@code{AC_TYPE_PID_T}
|
|
@item AC_PREFIX
|
|
@maindex PREFIX
|
|
@code{AC_PREFIX_PROGRAM}
|
|
@item AC_PROGRAMS_CHECK
|
|
@maindex PROGRAMS_CHECK
|
|
@code{AC_CHECK_PROGS}
|
|
@item AC_PROGRAMS_PATH
|
|
@maindex PROGRAMS_PATH
|
|
@code{AC_PATH_PROGS}
|
|
@item AC_PROGRAM_CHECK
|
|
@maindex PROGRAM_CHECK
|
|
@code{AC_CHECK_PROG}
|
|
@item AC_PROGRAM_EGREP
|
|
@maindex PROGRAM_EGREP
|
|
@code{AC_EGREP_CPP}
|
|
@item AC_PROGRAM_PATH
|
|
@maindex PROGRAM_PATH
|
|
@code{AC_PATH_PROG}
|
|
@item AC_REMOTE_TAPE
|
|
@maindex REMOTE_TAPE
|
|
removed because of limited usefulness
|
|
@item AC_RESTARTABLE_SYSCALLS
|
|
@maindex RESTARTABLE_SYSCALLS
|
|
@code{AC_SYS_RESTARTABLE_SYSCALLS}
|
|
@item AC_RETSIGTYPE
|
|
@maindex RETSIGTYPE
|
|
@code{AC_TYPE_SIGNAL}
|
|
@item AC_RSH
|
|
@maindex RSH
|
|
removed because of limited usefulness
|
|
@item AC_SCO_INTL
|
|
@maindex SCO_INTL
|
|
@code{AC_OS_SCO}
|
|
@item AC_SETVBUF_REVERSED
|
|
@maindex SETVBUF_REVERSED
|
|
@code{AC_FUNC_SETVBUF_REVERSED}
|
|
@item AC_SET_MAKE
|
|
@maindex SET_MAKE
|
|
@code{AC_PROG_MAKE_SET}
|
|
@item AC_SIZEOF_TYPE
|
|
@maindex SIZEOF_TYPE
|
|
@code{AC_CHECK_SIZEOF}
|
|
@item AC_SIZE_T
|
|
@maindex SIZE_T
|
|
@code{AC_TYPE_SIZE_T}
|
|
@item AC_STAT_MACROS_BROKEN
|
|
@maindex STAT_MACROS_BROKEN
|
|
@code{AC_HEADER_STAT}
|
|
@item AC_STDC_HEADERS
|
|
@maindex STDC_HEADERS
|
|
@code{AC_HEADER_STDC}
|
|
@item AC_STRCOLL
|
|
@maindex STRCOLL
|
|
@code{AC_FUNC_STRCOLL}
|
|
@item AC_ST_BLKSIZE
|
|
@maindex ST_BLKSIZE
|
|
@code{AC_STRUCT_ST_BLKSIZE}
|
|
@item AC_ST_BLOCKS
|
|
@maindex ST_BLOCKS
|
|
@code{AC_STRUCT_ST_BLOCKS}
|
|
@item AC_ST_RDEV
|
|
@maindex ST_RDEV
|
|
@code{AC_STRUCT_ST_RDEV}
|
|
@item AC_SYS_SIGLIST_DECLARED
|
|
@maindex SYS_SIGLIST_DECLARED
|
|
@code{AC_DECL_SYS_SIGLIST}
|
|
@item AC_TEST_CPP
|
|
@maindex TEST_CPP
|
|
@code{AC_TRY_CPP}
|
|
@item AC_TEST_PROGRAM
|
|
@maindex TEST_PROGRAM
|
|
@code{AC_TRY_RUN}
|
|
@item AC_TIMEZONE
|
|
@maindex TIMEZONE
|
|
@code{AC_STRUCT_TIMEZONE}
|
|
@item AC_TIME_WITH_SYS_TIME
|
|
@maindex TIME_WITH_SYS_TIME
|
|
@code{AC_HEADER_TIME}
|
|
@item AC_UID_T
|
|
@maindex UID_T
|
|
@code{AC_TYPE_UID_T}
|
|
@item AC_UTIME_NULL
|
|
@maindex UTIME_NULL
|
|
@code{AC_FUNC_UTIME_NULL}
|
|
@item AC_VFORK
|
|
@maindex VFORK
|
|
@code{AC_FUNC_VFORK}
|
|
@item AC_VPRINTF
|
|
@maindex VPRINTF
|
|
@code{AC_FUNC_VPRINTF}
|
|
@item AC_WAIT3
|
|
@maindex WAIT3
|
|
@code{AC_FUNC_WAIT3}
|
|
@item AC_WARN
|
|
@maindex WARN
|
|
@code{AC_MSG_WARN}
|
|
@item AC_WORDS_BIGENDIAN
|
|
@maindex WORDS_BIGENDIAN
|
|
@code{AC_C_BIGENDIAN}
|
|
@item AC_XENIX_DIR
|
|
@maindex XENIX_DIR
|
|
@code{AC_OS_XENIX}
|
|
@item AC_YYTEXT_POINTER
|
|
@maindex YYTEXT_POINTER
|
|
@code{AC_DECL_YYTEXT}
|
|
@end table
|
|
|
|
@node Environment Variable Index, Output Variable Index, Old Macro Names, Top
|
|
@unnumbered Environment Variable Index
|
|
|
|
This is an alphabetical list of the environment variables that Autoconf
|
|
checks.
|
|
|
|
@printindex ev
|
|
|
|
@node Output Variable Index, Preprocessor Symbol Index, Environment Variable Index, Top
|
|
@unnumbered Output Variable Index
|
|
|
|
This is an alphabetical list of the variables that Autoconf can
|
|
substitute into files that it creates, typically one or more
|
|
@file{Makefile}s. @xref{Setting Variables}, for more information on how
|
|
this is done.
|
|
|
|
@printindex ov
|
|
|
|
@node Preprocessor Symbol Index, Macro Index, Output Variable Index, Top
|
|
@unnumbered Preprocessor Symbol Index
|
|
|
|
This is an alphabetical list of the C preprocessor symbols that the
|
|
Autoconf macros define. To work with Autoconf, C source code needs to
|
|
use these names in @code{#if} directives.
|
|
|
|
@printindex cv
|
|
|
|
@node Macro Index, , Preprocessor Symbol Index, Top
|
|
@unnumbered Macro Index
|
|
|
|
This is an alphabetical list of the Autoconf macros. To make the list
|
|
easier to use, the macros are listed without their preceding @samp{AC_}.
|
|
|
|
@printindex ma
|
|
|
|
@contents
|
|
@bye
|
|
|
|
@c Local variables:
|
|
@c compile-command: "makeinfo autoconf.texi"
|
|
@c End:
|