\input texinfo @c -*-texinfo-*-
@comment ========================================================
@comment %**start of header
@setfilename autoconf.info
@include version.texi
@settitle Autoconf
@setchapternewpage odd
@ifnothtml
@setcontentsaftertitlepage
@end ifnothtml
@finalout
@c @ovar(ARG)
@c ----------
@c The ARG is an optional argument. To be used for macro arguments in
@c their documentation (@defmac).
@macro ovar{varname}
@r{[}@var{\varname\}@r{]}@c
@end macro
@c @dvar(ARG, DEFAULT)
@c -------------------
@c The ARG is an optional argument, defaulting to DEFAULT. To be used
@c for macro arguments in their documentation (@defmac).
@macro dvar{varname, default}
@r{[}@var{\varname\} = @samp{\default\}@r{]}@c
@end macro
@c Handling the indexes with Texinfo yields several different problems.
@c
@c Because we want to drop out the AC_ part of the macro names in the
@c printed manual, but not in the other outputs, we need a layer above
@c the usual @acindex{} etc. That's why we first define indexes such as
@c acx meant to become the macro @acindex. First of all, using ``ac_''
@c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
@c So use something more regular ``acx''. Then you finish with a printed
@c index saying ``index is not existent''. Of course: you ought to use
@c two letters :( So you use capitals.
@c
@c Second, when defining a macro in the TeX world, following spaces are
@c eaten. But then, since we embed @acxindex commands that use the end
@c of line as an end marker, the whole things wrecks itself. So make
@c sure you do *force* an additional end of line, add a ``@c''.
@c
@c Finally, you might want to get rid of TeX expansion, using --expand
@c with texi2dvi. But then you wake up an old problem: we use macros
@c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
@c Define an environment variable index, for variables users may set
@c in their environment or on the configure command line.
@defcodeindex ev
@c Define an output variable index, for commonly AC_SUBST'ed variables.
@defcodeindex ov
@c Define a cache variable index, for variables matching *_cv_*.
@defcodeindex CA
@c Other shell variables not fitting the above categories should be
@c listed in the predefined vrindex, which we merge in the concept index.
@syncodeindex vr cp
@c Define a CPP preprocessor macro index, for #define'd strings.
@defcodeindex cv
@c Define an Autoconf macro index that @defmac doesn't write to.
@defcodeindex AC
@c Define an Autotest macro index that @defmac doesn't write to.
@defcodeindex AT
@c Define an M4sugar macro index that @defmac doesn't write to.
@defcodeindex MS
@c Define an index for *foreign* programs: `mv' etc. Used for the
@c portability sections and so on.
@defindex pr
@c shortindexflag
@c --------------
@c Shall we factor AC_ out of the Autoconf macro index etc.?
@iftex
@set shortindexflag
@end iftex
@c @acindex{MACRO}
@c ---------------
@c Registering an AC_\MACRO\.
@ifset shortindexflag
@macro acindex{macro}
@ACindex \macro\
@c
@end macro
@end ifset
@ifclear shortindexflag
@macro acindex{macro}
@ACindex AC_\macro\
@end macro
@end ifclear
@c @ahindex{MACRO}
@c ---------------
@c Registering an AH_\MACRO\.
@macro ahindex{macro}
@ACindex AH_\macro\
@c
@end macro
@c @asindex{MACRO}
@c ---------------
@c Registering an AS_\MACRO\.
@ifset shortindexflag
@macro asindex{macro}
@MSindex \macro\
@c
@end macro
@end ifset
@ifclear shortindexflag
@macro asindex{macro}
@MSindex AS_\macro\
@end macro
@end ifclear
@c @atindex{MACRO}
@c ---------------
@c Registering an AT_\MACRO\.
@ifset shortindexflag
@macro atindex{macro}
@ATindex \macro\
@c
@end macro
@end ifset
@ifclear shortindexflag
@macro atindex{macro}
@ATindex AT_\macro\
@end macro
@end ifclear
@c @auindex{MACRO}
@c ---------------
@c Registering an AU_\MACRO\.
@macro auindex{macro}
@ACindex AU_\macro\
@c
@end macro
@c @hdrindex{MACRO}
@c ----------------
@c Indexing a header.
@macro hdrindex{macro}
@prindex @file{\macro\}
@c
@end macro
@c @msindex{MACRO}
@c ---------------
@c Registering an m4_\MACRO\.
@ifset shortindexflag
@macro msindex{macro}
@MSindex \macro\
@c
@end macro
@end ifset
@ifclear shortindexflag
@macro msindex{macro}
@MSindex m4_\macro\
@end macro
@end ifclear
@c @caindex{VARIABLE}
@c ------------------
@c Registering an ac_cv_\VARIABLE\ cache variable.
@ifset shortindexflag
@macro caindex{macro}
@CAindex \macro\
@end macro
@end ifset
@ifclear shortindexflag
@macro caindex{macro}
@CAindex ac_cv_\macro\
@end macro
@end ifclear
@c Define an index for functions: `alloca' etc. Used for the
@c portability sections and so on. We can't use `fn' (aka `fnindex),
@c since `@defmac' goes into it => we'd get all the macros too.
@c FIXME: Aaarg! It seems there are too many indices for TeX :(
@c
@c ! No room for a new @write .
@c l.112 @defcodeindex fu
@c
@c so don't define yet another one :( Just put some tags before each
@c @prindex which is actually a @funindex.
@c
@c @defcodeindex fu
@c
@c
@c @c Put the programs and functions into their own index.
@c @syncodeindex fu pr
@comment %**end of header
@comment ========================================================
@copying
This manual (@value{UPDATED}) is for GNU Autoconf
(version @value{VERSION}),
a package for creating scripts to configure source code packages using
templates and an M4 macro package.
Copyright @copyright{} 1992-1996, 1998-2012 Free Software Foundation,
Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover texts, and
no Back-Cover Texts. A copy of the license is included in the section
entitled ``GNU Free Documentation License.''
@end quotation
@end copying
@dircategory Software development
@direntry
* Autoconf: (autoconf). Create source code configuration scripts.
@end direntry
@dircategory Individual utilities
@direntry
* autoscan: (autoconf)autoscan Invocation.
Semi-automatic @file{configure.ac} writing
* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
* autoconf-invocation: (autoconf)autoconf Invocation.
How to create configuration scripts
* autoreconf: (autoconf)autoreconf Invocation.
Remaking multiple @command{configure} scripts
* autoheader: (autoconf)autoheader Invocation.
How to create configuration templates
* autom4te: (autoconf)autom4te Invocation.
The Autoconf executables backbone
* configure: (autoconf)configure Invocation. Configuring a package.
* autoupdate: (autoconf)autoupdate Invocation.
Automatic update of @file{configure.ac}
* config.status: (autoconf)config.status Invocation. Recreating configurations.
* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
@end direntry
@titlepage
@title Autoconf
@subtitle Creating Automatic Configuration Scripts
@subtitle for version @value{VERSION}, @value{UPDATED}
@author David MacKenzie
@author Ben Elliston
@author Akim Demaille
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top Autoconf
@insertcopying
@end ifnottex
@c The master menu, created with texinfo-master-menu, goes here.
@menu
* Introduction:: Autoconf's purpose, strengths, and weaknesses
* The GNU Build System:: A set of tools for portable software packages
* Making configure Scripts:: How to organize and produce Autoconf scripts
* Setup:: Initialization and output
* Existing Tests:: Macros that check for particular features
* Writing Tests:: How to write new feature checks
* Results:: What to do with results from feature checks
* Programming in M4:: Layers on top of which Autoconf is written
* Programming in M4sh:: Shell portability layer
* Writing Autoconf Macros:: Adding new macros to Autoconf
* Portable Shell:: Shell script portability pitfalls
* Portable Make:: Makefile portability pitfalls
* Portable C and C++:: C and C++ portability pitfalls
* Manual Configuration:: Selecting features that can't be guessed
* Site Configuration:: Local defaults for @command{configure}
* Running configure Scripts:: How to use the Autoconf output
* config.status Invocation:: Recreating a configuration
* Obsolete Constructs:: Kept for backward compatibility
* Using Autotest:: Creating portable test suites
* FAQ:: Frequent Autoconf Questions, with answers
* History:: History of Autoconf
* GNU Free Documentation License:: License for copying this manual
* Indices:: Indices of symbols, concepts, etc.
@detailmenu
--- The Detailed Node Listing ---
The GNU Build System
* Automake:: Escaping makefile hell
* Gnulib:: The GNU portability library
* Libtool:: Building libraries portably
* Pointers:: More info on the GNU build system
Making @command{configure} Scripts
* Writing Autoconf Input:: What to put in an Autoconf input file
* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
* ifnames Invocation:: Listing the conditionals in source code
* autoconf Invocation:: How to create configuration scripts
* autoreconf Invocation:: Remaking multiple @command{configure} scripts
Writing @file{configure.ac}
* Shell Script Compiler:: Autoconf as solution of a problem
* Autoconf Language:: Programming in Autoconf
* Autoconf Input Layout:: Standard organization of @file{configure.ac}
Initialization and Output Files
* Initializing configure:: Option processing etc.
* Versioning:: Dealing with Autoconf versions
* Notices:: Copyright, version numbers in @command{configure}
* Input:: Where Autoconf should find files
* Output:: Outputting results from the configuration
* Configuration Actions:: Preparing the output based on results
* Configuration Files:: Creating output files
* Makefile Substitutions:: Using output variables in makefiles
* Configuration Headers:: Creating a configuration header file
* Configuration Commands:: Running arbitrary instantiation commands
* Configuration Links:: Links depending on the configuration
* Subdirectories:: Configuring independent packages together
* Default Prefix:: Changing the default installation prefix
Substitutions in Makefiles
* Preset Output Variables:: Output variables that are always set
* Installation Directory Variables:: Other preset output variables
* Changed Directory Variables:: Warnings about @file{datarootdir}
* Build Directories:: Supporting multiple concurrent compiles
* Automatic Remaking:: Makefile rules for configuring
Configuration Header Files
* Header Templates:: Input for the configuration headers
* autoheader Invocation:: How to create configuration templates
* Autoheader Macros:: How to specify CPP templates
Existing Tests
* Common Behavior:: Macros' standard schemes
* Alternative Programs:: Selecting between alternative programs
* Files:: Checking for the existence of files
* Libraries:: Library archives that might be missing
* Library Functions:: C library functions that might be missing
* Header Files:: Header files that might be missing
* Declarations:: Declarations that may be missing
* Structures:: Structures or members that might be missing
* Types:: Types that might be missing
* Compilers and Preprocessors:: Checking for compiling programs
* System Services:: Operating system services
* Posix Variants:: Special kludges for specific Posix variants
* Erlang Libraries:: Checking for the existence of Erlang libraries
Common Behavior
* Standard Symbols:: Symbols defined by the macros
* Default Includes:: Includes used by the generic macros
Alternative Programs
* Particular Programs:: Special handling to find certain programs
* Generic Programs:: How to find other programs
Library Functions
* Function Portability:: Pitfalls with usual functions
* Particular Functions:: Special handling to find certain functions
* Generic Functions:: How to find other functions
Header Files
* Header Portability:: Collected knowledge on common headers
* Particular Headers:: Special handling to find certain headers
* Generic Headers:: How to find other headers
Declarations
* Particular Declarations:: Macros to check for certain declarations
* Generic Declarations:: How to find other declarations
Structures
* Particular Structures:: Macros to check for certain structure members
* Generic Structures:: How to find other structure members
Types
* Particular Types:: Special handling to find certain types
* Generic Types:: How to find other types
Compilers and Preprocessors
* Specific Compiler Characteristics:: Some portability issues
* Generic Compiler Characteristics:: Language independent tests and features
* C Compiler:: Checking its characteristics
* C++ Compiler:: Likewise
* Objective C Compiler:: Likewise
* Objective C++ Compiler:: Likewise
* Erlang Compiler and Interpreter:: Likewise
* Fortran Compiler:: Likewise
* Go Compiler:: Likewise
Writing Tests
* Language Choice:: Selecting which language to use for testing
* Writing Test Programs:: Forging source files for compilers
* Running the Preprocessor:: Detecting preprocessor symbols
* Running the Compiler:: Detecting language or header features
* Running the Linker:: Detecting library features
* Runtime:: Testing for runtime features
* Systemology:: A zoology of operating systems
* Multiple Cases:: Tests for several possible values
Writing Test Programs
* Guidelines:: General rules for writing test programs
* Test Functions:: Avoiding pitfalls in test programs
* Generating Sources:: Source program boilerplate
Results of Tests
* Defining Symbols:: Defining C preprocessor symbols
* Setting Output Variables:: Replacing variables in output files
* Special Chars in Variables:: Characters to beware of in variables
* Caching Results:: Speeding up subsequent @command{configure} runs
* Printing Messages:: Notifying @command{configure} users
Caching Results
* Cache Variable Names:: Shell variables used in caches
* Cache Files:: Files @command{configure} uses for caching
* Cache Checkpointing:: Loading and saving the cache file
Programming in M4
* M4 Quotation:: Protecting macros from unwanted expansion
* Using autom4te:: The Autoconf executables backbone
* Programming in M4sugar:: Convenient pure M4 macros
* Debugging via autom4te:: Figuring out what M4 was doing
M4 Quotation
* Active Characters:: Characters that change the behavior of M4
* One Macro Call:: Quotation and one macro call
* Quoting and Parameters:: M4 vs. shell parameters
* Quotation and Nested Macros:: Macros calling macros
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
* Quadrigraphs:: Another way to escape special characters
* Balancing Parentheses:: Dealing with unbalanced parentheses
* Quotation Rule Of Thumb:: One parenthesis, one quote
Using @command{autom4te}
* autom4te Invocation:: A GNU M4 wrapper
* Customizing autom4te:: Customizing the Autoconf package
Programming in M4sugar
* Redefined M4 Macros:: M4 builtins changed in M4sugar
* Diagnostic Macros:: Diagnostic messages from M4sugar
* Diversion support:: Diversions in M4sugar
* Conditional constructs:: Conditions in M4
* Looping constructs:: Iteration in M4
* Evaluation Macros:: More quotation and evaluation control
* Text processing Macros:: String manipulation in M4
* Number processing Macros:: Arithmetic computation in M4
* Set manipulation Macros:: Set manipulation in M4
* Forbidden Patterns:: Catching unexpanded macros
Programming in M4sh
* Common Shell Constructs:: Portability layer for common shell constructs
* Polymorphic Variables:: Support for indirect variable names
* Initialization Macros:: Macros to establish a sane shell environment
* File Descriptor Macros:: File descriptor macros for input and output
Writing Autoconf Macros
* Macro Definitions:: Basic format of an Autoconf macro
* Macro Names:: What to call your new macros
* Reporting Messages:: Notifying @command{autoconf} users
* Dependencies Between Macros:: What to do when macros depend on other macros
* Obsoleting Macros:: Warning about old ways of doing things
* Coding Style:: Writing Autoconf macros @`a la Autoconf
Dependencies Between Macros
* Prerequisite Macros:: Ensuring required information
* Suggested Ordering:: Warning about possible ordering problems
* One-Shot Macros:: Ensuring a macro is called only once
Portable Shell Programming
* Shellology:: A zoology of shells
* Invoking the Shell:: Invoking the shell as a command
* Here-Documents:: Quirks and tricks
* File Descriptors:: FDs and redirections
* Signal Handling:: Shells, signals, and headaches
* File System Conventions:: File names
* Shell Pattern Matching:: Pattern matching
* Shell Substitutions:: Variable and command expansions
* Assignments:: Varying side effects of assignments
* Parentheses:: Parentheses in shell scripts
* Slashes:: Slashes in shell scripts
* Special Shell Variables:: Variables you should not change
* Shell Functions:: What to look out for if you use them
* Limitations of Builtins:: Portable use of not so portable /bin/sh
* Limitations of Usual Tools:: Portable use of portable tools
Portable Make Programming
* $< in Ordinary Make Rules:: $< in ordinary rules
* Failure in Make Rules:: Failing portably in rules
* Special Chars in Names:: Special Characters in Macro Names
* Backslash-Newline-Empty:: Empty lines after backslash-newline
* Backslash-Newline Comments:: Spanning comments across line boundaries
* Long Lines in Makefiles:: Line length limitations
* Macros and Submakes:: @code{make macro=value} and submakes
* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
* The Make Macro SHELL:: @code{$(SHELL)} portability issues
* Parallel Make:: Parallel @command{make} quirks
* Comments in Make Rules:: Other problems with Make comments
* Newlines in Make Rules:: Using literal newlines in rules
* Comments in Make Macros:: Other problems with Make comments in macros
* Trailing whitespace in Make Macros:: Macro substitution problems
* Command-line Macros and whitespace:: Whitespace trimming of values
* obj/ and Make:: Don't name a subdirectory @file{obj}
* make -k Status:: Exit status of @samp{make -k}
* VPATH and Make:: @code{VPATH} woes
* Single Suffix Rules:: Single suffix rules and separated dependencies
* Timestamps and Make:: Subsecond timestamp resolution
@code{VPATH} and Make
* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts
* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
* $< in Explicit Rules:: @code{$<} does not work in ordinary rules
* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
* Make Target Lookup:: More details about @code{VPATH} lookup
Portable C and C++ Programming
* Varieties of Unportability:: How to make your programs unportable
* Integer Overflow:: When integers get too large
* Preprocessor Arithmetic:: @code{#if} expression problems
* Null Pointers:: Properties of null pointers
* Buffer Overruns:: Subscript errors and the like
* Volatile Objects:: @code{volatile} and signals
* Floating Point Portability:: Portable floating-point arithmetic
* Exiting Portably:: Exiting and the exit status
Integer Overflow
* Integer Overflow Basics:: Why integer overflow is a problem
* Signed Overflow Examples:: Examples of code assuming wraparound
* Optimization and Wraparound:: Optimizations that break uses of wraparound
* Signed Overflow Advice:: Practical advice for signed overflow issues
* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
Manual Configuration
* Specifying Target Triplets:: Specifying target triplets
* Canonicalizing:: Getting the canonical system type
* Using System Type:: What to do with the system type
Site Configuration
* Help Formatting:: Customizing @samp{configure --help}
* External Software:: Working with other optional software
* Package Options:: Selecting optional features
* Pretty Help Strings:: Formatting help string
* Option Checking:: Controlling checking of @command{configure} options
* Site Details:: Configuring site details
* Transforming Names:: Changing program names when installing
* Site Defaults:: Giving @command{configure} local defaults
Transforming Program Names When Installing
* Transformation Options:: @command{configure} options to transform names
* Transformation Examples:: Sample uses of transforming names
* Transformation Rules:: Makefile uses of transforming names
Running @command{configure} Scripts
* Basic Installation:: Instructions for typical cases
* Compilers and Options:: Selecting compilers and optimization
* Multiple Architectures:: Compiling for multiple architectures at once
* Installation Names:: Installing in different directories
* Optional Features:: Selecting optional features
* Particular Systems:: Particular systems
* System Type:: Specifying the system type
* Sharing Defaults:: Setting site-wide defaults for @command{configure}
* Defining Variables:: Specifying the compiler etc.
* configure Invocation:: Changing how @command{configure} runs
Obsolete Constructs
* Obsolete config.status Use:: Obsolete convention for @command{config.status}
* acconfig Header:: Additional entries in @file{config.h.in}
* autoupdate Invocation:: Automatic update of @file{configure.ac}
* Obsolete Macros:: Backward compatibility macros
* Autoconf 1:: Tips for upgrading your files
* Autoconf 2.13:: Some fresher tips
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
Upgrading From Version 2.13
* Changed Quotation:: Broken code which used to work
* New Macros:: Interaction with foreign macros
* Hosts and Cross-Compilation:: Bugward compatibility kludges
* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources
Generating Test Suites with Autotest
* Using an Autotest Test Suite:: Autotest and the user
* Writing Testsuites:: Autotest macros
* testsuite Invocation:: Running @command{testsuite} scripts
* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
Using an Autotest Test Suite
* testsuite Scripts:: The concepts of Autotest
* Autotest Logs:: Their contents
Frequent Autoconf Questions, with answers
* Distributing:: Distributing @command{configure} scripts
* Why GNU M4:: Why not use the standard M4?
* Bootstrapping:: Autoconf and GNU M4 require each other?
* Why Not Imake:: Why GNU uses @command{configure} instead of Imake
* Defining Directories:: Passing @code{datadir} to program
* Autom4te Cache:: What is it? Can I remove it?
* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
* Expanded Before Required:: Expanded Before Required
* Debugging:: Debugging @command{configure} scripts
History of Autoconf
* Genesis:: Prehistory and naming of @command{configure}
* Exodus:: The plagues of M4 and Perl
* Leviticus:: The priestly code of portability arrives
* Numbers:: Growth and contributors
* Deuteronomy:: Approaching the promises of easy configuration
Indices
* 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
* Cache Variable Index:: Index of documented cache variables
* Autoconf Macro Index:: Index of Autoconf macros
* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
* Autotest Macro Index:: Index of Autotest macros
* Program & Function Index:: Index of those with portability problems
* Concept Index:: General index
@end detailmenu
@end menu
@c ============================================================= Introduction.
@node Introduction
@chapter Introduction
@cindex Introduction
@flushright
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, Maxwell's
equations, the dual nature of electromagnetic waves, the relativistic
consequences@enddots{}'' ``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@enddots{}'' The computer scientist
shouted: ``And the Chaos, where do you think it was coming from, hmm?''
---Anonymous
@end flushright
@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
Posix-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 individually test for the
presence of each feature that the software package they are for might need.
(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 Posix variants. There is
no need to maintain files that list the features supported by each
release of each variant of Posix.
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.
@c "Those who do not understand Unix are condemned to reinvent it, poorly."
@c --Henry Spencer, 1987 (see
http://en.wikipedia.org/wiki/Unix_philosophy)
Those who do not understand Autoconf are condemned to reinvent it, poorly.
The primary goal of Autoconf is making the @emph{user's} life easier;
making the @emph{maintainer's} life easier is only a secondary goal.
Put another way, the primary goal is not to make the generation of
@file{configure} automatic for package maintainers (although patches
along that front are welcome, since package maintainers form the user
base of Autoconf); rather, the goal is to make @file{configure}
painless, portable, and predictable for the end user of each
@dfn{autoconfiscated} package. And to this degree, Autoconf is highly
successful at its goal --- most complaints to the Autoconf list are
about difficulties in writing Autoconf input, and not in the behavior of
the resulting @file{configure}. Even packages that don't use Autoconf
will generally provide a @file{configure} script, and the most common
complaint about these alternative home-grown scripts is that they fail
to meet one or more of the GNU Coding Standards (@pxref{Configuration, , ,
standards, The GNU Coding Standards}) that users
have come to expect from Autoconf-generated @file{configure} scripts.
The 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 does not solve all problems related to making portable
software packages---for a more complete solution, it should be used in
concert with other GNU build tools like Automake and
Libtool. These other tools take on jobs like the creation of a
portable, recursive makefile with all of the standard targets,
linking of shared libraries, and so on. @xref{The GNU Build System},
for more information.
Autoconf imposes some restrictions on the names of macros used with
@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
Autoconf requires GNU M4 version 1.4.6 or later in order to
generate the scripts. It uses features that some versions of M4,
including GNU M4 1.3, do not have. Autoconf works better
with GNU M4 version 1.4.14 or later, though this is not
required.
@xref{Autoconf 1}, for information about upgrading from version 1.
@xref{History}, for the story of Autoconf's development. @xref{FAQ},
for answers to some common questions about Autoconf.
See the @uref{http://@/www.gnu.org/@/software/@/autoconf/,
Autoconf web page} for up-to-date information, details on the mailing
lists, pointers to a list of known bugs, etc.
Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
list}. Past suggestions are
@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf/, archived}.
Mail bug reports to @email{bug-autoconf@@gnu.org, the
Autoconf Bugs mailing list}. Past bug reports are
@uref{http://@/lists.gnu.org/@/archive/@/html/@/bug-autoconf/, archived}.
If possible, first check that your bug is
not already solved in current development versions, and that it has not
been reported yet. Be sure to include all the needed information and a
short @file{configure.ac} that demonstrates the problem.
Autoconf's development tree is accessible via @command{git}; see the
@uref{http://@/savannah.gnu.org/@/projects/@/autoconf/, Autoconf
Summary} for details, or view
@uref{http://@/git.sv.gnu.org/@/gitweb/@/?p=autoconf.git, the actual
repository}. Anonymous CVS access is also available, see
@file{README} for more details. Patches relative to the
current @command{git} version can be sent for review to the
@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}, with
discussion on prior patches
@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-@/patches/,
archived}; and all commits are posted in the read-only
@email{autoconf-commit@@gnu.org, Autoconf Commit mailing list}, which is
also @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-commit/,
archived}.
Because of its mission, the Autoconf package itself
includes only a set of often-used
macros that have already demonstrated their usefulness. Nevertheless,
if you wish to share your macros, or find existing ones, see the
@uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
Archive}, which is kindly run by @email{simons@@cryp.to,
Peter Simons}.
@c ================================================= The GNU Build System
@node The GNU Build System
@chapter The GNU Build System
@cindex GNU build system
Autoconf solves an important problem---reliable discovery of
system-specific build and runtime information---but this is only one
piece of the puzzle for the development of portable software. To this
end, the GNU project has developed a suite of integrated
utilities to finish the job Autoconf started: the GNU build
system, whose most important components are Autoconf, Automake, and
Libtool. In this chapter, we introduce you to those tools, point you
to sources of more information, and try to convince you to use the
entire GNU build system for your software.
@menu
* Automake:: Escaping makefile hell
* Gnulib:: The GNU portability library
* Libtool:: Building libraries portably
* Pointers:: More info on the GNU build system
@end menu
@node Automake
@section Automake
The ubiquity of @command{make} means that a makefile is almost the
only viable way to distribute automatic build rules for software, but
one quickly runs into its numerous limitations. Its lack of
support for automatic dependency tracking, recursive builds in
subdirectories, reliable timestamps (e.g., for network file systems), and
so on, mean that developers must painfully (and often incorrectly)
reinvent the wheel for each project. Portability is non-trivial, thanks
to the quirks of @command{make} on many systems. On top of all this is the
manual labor required to implement the many standard targets that users
have come to expect (@code{make install}, @code{make distclean},
@code{make uninstall}, etc.). Since you are, of course, using Autoconf,
you also have to insert repetitive code in your @file{Makefile.in} to
recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
provided by @command{configure}. Into this mess steps @dfn{Automake}.
@cindex Automake
Automake allows you to specify your build needs in a @file{Makefile.am}
file with a vastly simpler and more powerful syntax than that of a plain
makefile, and then generates a portable @file{Makefile.in} for
use with Autoconf. For example, the @file{Makefile.am} to build and
install a simple ``Hello world'' program might look like:
@example
bin_PROGRAMS = hello
hello_SOURCES = hello.c
@end example
@noindent
The resulting @file{Makefile.in} (~400 lines) automatically supports all
the standard targets, the substitutions provided by Autoconf, automatic
dependency tracking, @code{VPATH} building, and so on. @command{make}
builds the @code{hello} program, and @code{make install} installs it
in @file{/usr/local/bin} (or whatever prefix was given to
@command{configure}, if not @file{/usr/local}).
The benefits of Automake increase for larger packages (especially ones
with subdirectories), but even for small programs the added convenience
and portability can be substantial. And that's not all@enddots{}
@node Gnulib
@section Gnulib
GNU software has a well-deserved reputation for running on
many different types of systems. While our primary goal is to write
software for the GNU system, many users and developers have
been introduced to us through the systems that they were already using.
@cindex Gnulib
Gnulib is a central location for common GNU code, intended to
be shared among free software packages. Its components are typically
shared at the source level, rather than being a library that gets built,
installed, and linked against. The idea is to copy files from Gnulib
into your own source tree. There is no distribution tarball; developers
should just grab source modules from the repository. The source files
are available online, under various licenses, mostly GNU
GPL or GNU LGPL.
Gnulib modules typically contain C source code along with Autoconf
macros used to configure the source code. For example, the Gnulib
@code{stdbool} module implements a @file{stdbool.h} header that nearly
conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
This module contains a source file for the replacement header, along
with an Autoconf macro that arranges to use the replacement header on
old-fashioned systems.
@node Libtool
@section Libtool
Often, one wants to build not only programs, but libraries, so that
other programs can benefit from the fruits of your labor. Ideally, one
would like to produce @emph{shared} (dynamically linked) libraries,
which can be used by multiple programs without duplication on disk or in
memory and can be updated independently of the linked programs.
Producing shared libraries portably, however, is the stuff of
nightmares---each system has its own incompatible tools, compiler flags,
and magic incantations. Fortunately, GNU provides a solution:
@dfn{Libtool}.
@cindex Libtool
Libtool handles all the requirements of building shared libraries for
you, and at this time seems to be the @emph{only} way to do so with any
portability. It also handles many other headaches, such as: the
interaction of Make rules with the variable suffixes of
shared libraries, linking reliably with shared libraries before they are
installed by the superuser, and supplying a consistent versioning system
(so that different versions of a library can be installed or upgraded
without breaking binary compatibility). Although Libtool, like
Autoconf, can be used without Automake, it is most simply utilized in
conjunction with Automake---there, Libtool is used automatically
whenever shared libraries are needed, and you need not know its syntax.
@node Pointers
@section Pointers
Developers who are used to the simplicity of @command{make} for small
projects on a single system might be daunted at the prospect of
learning to use Automake and Autoconf. As your software is
distributed to more and more users, however, you otherwise
quickly find yourself putting lots of effort into reinventing the
services that the GNU build tools provide, and making the
same mistakes that they once made and overcame. (Besides, since
you're already learning Autoconf, Automake is a piece of cake.)
There are a number of places that you can go to for more information on
the GNU build tools.
@itemize @minus
@item Web
The project home pages for
@uref{http://@/www@/.gnu@/.org/@/software/@/autoconf/, Autoconf},
@uref{http://@/www@/.gnu@/.org/@/software/@/automake/, Automake},
@uref{http://@/www@/.gnu@/.org/@/software/@/gnulib/, Gnulib}, and
@uref{http://@/www@/.gnu@/.org/@/software/@/libtool/, Libtool}.
@item Automake Manual
@xref{Top, , Automake, automake, GNU Automake}, for more
information on Automake.
@item Books
The book @cite{GNU Autoconf, Automake and
Libtool}@footnote{@cite{GNU Autoconf, Automake and Libtool},
by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
New Riders), 2000, ISBN 1578701902.} describes the complete GNU
build environment. You can also find
@uref{http://@/sources.redhat.com/@/autobook/, the entire book on-line}.
@end itemize
@c ================================================= Making configure Scripts.
@node Making configure Scripts
@chapter Making @command{configure} Scripts
@cindex @file{aclocal.m4}
@cindex @command{configure}
The configuration scripts that Autoconf produces are by convention
called @command{configure}. When run, @command{configure} creates several
files, replacing configuration parameters in them with appropriate
values. The files that @command{configure} creates are:
@itemize @minus
@item
one or more @file{Makefile} files, usually one in each subdirectory of the
package (@pxref{Makefile Substitutions});
@item
optionally, a C header file, the name of which is configurable,
containing @code{#define} directives (@pxref{Configuration Headers});
@item
a shell script called @file{config.status} that, when run, recreates
the files listed above (@pxref{config.status Invocation});
@item
an optional shell script normally called @file{config.cache}
(created when using @samp{configure --config-cache}) that
saves the results of running many of the tests (@pxref{Cache Files});
@item
a file called @file{config.log} containing any messages produced by
compilers, to help debugging if @command{configure} makes a mistake.
@end itemize
@cindex @file{configure.in}
@cindex @file{configure.ac}
To create a @command{configure} script with Autoconf, you need to write an
Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
@command{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 run
@command{autoheader}, and you can distribute the 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{[]}).
@command{autoconf} and @command{autoheader} also read the installed Autoconf
macro files (by reading @file{autoconf.m4}).
@noindent
Files used in preparing a software package for distribution, when using
just Autoconf:
@example
your source files --> [autoscan*] --> [configure.scan] --> configure.ac
@group
configure.ac --.
| .------> autoconf* -----> configure
[aclocal.m4] --+---+
| `-----> [autoheader*] --> [config.h.in]
[acsite.m4] ---'
@end group
Makefile.in
@end example
@noindent
Additionally, if you use Automake, the following additional productions
come into play:
@example
@group
[acinclude.m4] --.
|
[local macros] --+--> aclocal* --> aclocal.m4
|
configure.ac ----'
@end group
@group
configure.ac --.
+--> automake* --> Makefile.in
Makefile.am ---'
@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 Autoconf Input:: What to put in an Autoconf input file
* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
* ifnames Invocation:: Listing the conditionals in source code
* autoconf Invocation:: How to create configuration scripts
* autoreconf Invocation:: Remaking multiple @command{configure} scripts
@end menu
@node Writing Autoconf Input
@section Writing @file{configure.ac}
To produce a @command{configure} script for a software package, create a
file called @file{configure.ac} 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{Writing Tests}, for information about them. For especially tricky
or specialized features, @file{configure.ac} might need to contain some
hand-crafted shell commands; see @ref{Portable Shell, , Portable Shell
Programming}. The @command{autoscan} program can give you a good start
in writing @file{configure.ac} (@pxref{autoscan Invocation}, for more
information).
Previous versions of Autoconf promoted the name @file{configure.in},
which is somewhat ambiguous (the tool needed to process this file is not
described by its extension), and introduces a slight confusion with
@file{config.h.in} and so on (for which @samp{.in} means ``to be
processed by @command{configure}''). Using @file{configure.ac} is now
preferred.
@menu
* Shell Script Compiler:: Autoconf as solution of a problem
* Autoconf Language:: Programming in Autoconf
* Autoconf Input Layout:: Standard organization of @file{configure.ac}
@end menu
@node Shell Script Compiler
@subsection A Shell Script Compiler
Just as for any other computer language, in order to properly program
@file{configure.ac} in Autoconf you must understand @emph{what} problem
the language tries to address and @emph{how} it does so.
The problem Autoconf addresses is that the world is a mess. After all,
you are using Autoconf in order to have your package compile easily on
all sorts of different systems, some of them being extremely hostile.
Autoconf itself bears the price for these differences: @command{configure}
must run on all those systems, and thus @command{configure} must limit itself
to their lowest common denominator of features.
Naturally, you might then think of shell scripts; who needs
@command{autoconf}? A set of properly written shell functions is enough to
make it easy to write @command{configure} scripts by hand. Sigh!
Unfortunately, even in 2008, where shells without any function support are
far and few between, there are pitfalls to avoid when making use of them.
Also, finding a Bourne shell that accepts shell functions is not trivial,
even though there is almost always one on interesting porting targets.
So, what is really needed is some kind of compiler, @command{autoconf},
that takes an Autoconf program, @file{configure.ac}, and transforms it
into a portable shell script, @command{configure}.
How does @command{autoconf} perform this task?
There are two obvious possibilities: creating a brand new language or
extending an existing one. The former option is attractive: all
sorts of optimizations could easily be implemented in the compiler and
many rigorous checks could be performed on the Autoconf program
(e.g., rejecting any non-portable construct). Alternatively, you can
extend an existing language, such as the @code{sh} (Bourne shell)
language.
Autoconf does the latter: it is a layer on top of @code{sh}. It was
therefore most convenient to implement @command{autoconf} as a macro
expander: a program that repeatedly performs @dfn{macro expansions} on
text input, replacing macro calls with macro bodies and producing a pure
@code{sh} script in the end. Instead of implementing a dedicated
Autoconf macro expander, it is natural to use an existing
general-purpose macro language, such as M4, and implement the extensions
as a set of M4 macros.
@node Autoconf Language
@subsection The Autoconf Language
@cindex quotation
The Autoconf language differs from many other computer
languages because it treats actual code the same as plain text. Whereas
in C, for instance, data and instructions have different syntactic
status, in Autoconf their status is rigorously the same. Therefore, we
need a means to distinguish literal strings from text to be expanded:
quotation.
When calling macros that take arguments, there must not be any white
space between the macro name and the open parenthesis.
@example
AC_INIT ([oops], [1.0]) # incorrect
AC_INIT([hello], [1.0]) # good
@end example
Arguments should
be enclosed within the quote characters @samp{[} and @samp{]}, and be
separated by commas. Any leading blanks or newlines in arguments are ignored,
unless they are quoted. You should always quote an argument that
might contain a macro name, comma, parenthesis, or a leading blank or
newline. This rule applies recursively for every macro
call, including macros called from other macros. For more details on
quoting rules, see @ref{Programming in M4}.
For instance:
@example
AC_CHECK_HEADER([stdio.h],
[AC_DEFINE([HAVE_STDIO_H], [1],
[Define to 1 if you have <stdio.h>.])],
[AC_MSG_ERROR([sorry, can't do anything for you])])
@end example
@noindent
is quoted properly. You may safely simplify its quotation to:
@example
AC_CHECK_HEADER([stdio.h],
[AC_DEFINE([HAVE_STDIO_H], 1,
[Define to 1 if you have <stdio.h>.])],
[AC_MSG_ERROR([sorry, can't do anything for you])])
@end example
@noindent
because @samp{1} cannot contain a macro call. Here, the argument of
@code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
interpreted as an argument separator. Also, the second and third arguments
of @samp{AC_CHECK_HEADER} must be quoted, since they contain
macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
if you unwisely defined a macro with a name like @samp{Define} or
@samp{stdio} then they would need quoting. Cautious Autoconf users
would keep the quotes, but many Autoconf users find such precautions
annoying, and would rewrite the example as follows:
@example
AC_CHECK_HEADER(stdio.h,
[AC_DEFINE(HAVE_STDIO_H, 1,
[Define to 1 if you have <stdio.h>.])],
[AC_MSG_ERROR([sorry, can't do anything for you])])
@end example
@noindent
This is safe, so long as you adopt good naming conventions and do not
define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
@samp{h}. Though it is also safe here to omit the quotes around
@samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
message strings are more likely to inadvertently contain commas.
The following example is wrong and dangerous, as it is underquoted:
@example
AC_CHECK_HEADER(stdio.h,
AC_DEFINE(HAVE_STDIO_H, 1,
Define to 1 if you have <stdio.h>.),
AC_MSG_ERROR([sorry, can't do anything for you]))
@end example
In other cases, you may have to use text that also resembles a macro
call. You must quote that text even when it is not passed as a macro
argument. For example, these two approaches in @file{configure.ac}
(quoting just the potential problems, or quoting the entire line) will
protect your script in case autoconf ever adds a macro @code{AC_DC}:
@example
echo "Hard rock was here! --[AC_DC]"
[echo "Hard rock was here! --AC_DC"]
@end example
@noindent
which results in this text in @file{configure}:
@example
echo "Hard rock was here! --AC_DC"
echo "Hard rock was here! --AC_DC"
@end example
@noindent
When you use the same text in a macro argument, you must therefore have
an extra quotation level (since one is stripped away by the macro
substitution). In general, then, it is a good idea to @emph{use double
quoting for all literal string arguments}, either around just the
problematic portions, or over the entire argument:
@example
AC_MSG_WARN([[AC_DC] stinks --Iron Maiden])
AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
@end example
However, the above example triggers a warning about a possibly
unexpanded macro when running @command{autoconf}, because it collides
with the namespace of macros reserved for the Autoconf language. To be
really safe, you can use additional escaping (either a quadrigraph, or
creative shell constructs) to silence that particular warning:
@example
echo "Hard rock was here! --AC""_DC"
AC_MSG_WARN([[AC@@&t@@_DC stinks --Iron Maiden]])
@end example
You are now able to understand one of the constructs of Autoconf that
has been continually misunderstood@enddots{} The rule of thumb is that
@emph{whenever you expect macro expansion, expect quote expansion};
i.e., expect one level of quotes to be lost. For instance:
@example
AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [],
[AC_MSG_ERROR([you lose])])
@end example
@noindent
is incorrect: here, the first argument of @code{AC_LANG_SOURCE} is
@samp{char b[10];} and is expanded once, which results in
@samp{char b10;}; and the @code{AC_LANG_SOURCE} is also expanded prior
to being passed to @code{AC_COMPILE_IFELSE}. (There was an idiom common
in Autoconf's past to
address this issue via the M4 @code{changequote} primitive, but do not
use it!) Let's take a closer look: the author meant the first argument
to be understood as a literal, and therefore it must be quoted twice;
likewise, the intermediate @code{AC_LANG_SOURCE} macro should be quoted
once so that it is only expanded after the rest of the body of
@code{AC_COMPILE_IFELSE} is in place:
@example
AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [],
[AC_MSG_ERROR([you lose])])
@end example
@noindent
Voil@`a, you actually produce @samp{char b[10];} this time!
On the other hand, descriptions (e.g., the last parameter of
@code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
are subject to line breaking, for example---and should not be double quoted.
Even if these descriptions are short and are not actually broken, double
quoting them yields weird results.
Some macros take optional arguments, which this documentation represents
as @ovar{arg} (not to be confused with the quote characters). You may
just leave them empty, or use @samp{[]} to make the emptiness of the
argument explicit, or you may simply omit the trailing commas. The
three lines below are equivalent:
@example
AC_CHECK_HEADERS([stdio.h], [], [], [])
AC_CHECK_HEADERS([stdio.h],,,)
AC_CHECK_HEADERS([stdio.h])
@end example
It is best to put each macro call on its own line in
@file{configure.ac}. Most of the macros don't add extra newlines; they
rely on the newline after the macro call to terminate the commands.
This approach makes the generated @command{configure} script a little
easier to read by not inserting lots of blank lines. It is generally
safe to set shell variables on the same line as a macro call, because
the shell allows assignments without intervening newlines.
You can include comments in @file{configure.ac} files by starting them
with the @samp{#}. For example, it is helpful to begin
@file{configure.ac} files with a line like this:
@example
# Process this file with autoconf to produce a configure script.
@end example
@node Autoconf Input Layout
@subsection Standard @file{configure.ac} Layout
The order in which @file{configure.ac} calls the Autoconf macros is not
important, with a few exceptions. Every @file{configure.ac} 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 when @command{configure} is created if they
are called out of order.
To encourage consistency, here is a suggested order for calling the
Autoconf macros. Generally speaking, the things near the end of this
list are those that could depend on things earlier in it. For example,
library functions could be affected by types and libraries.
@display
@group
Autoconf requirements
@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
information on the package
checks for programs
checks for libraries
checks for header files
checks for types
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
@code{AC_OUTPUT}
@end group
@end display
@node autoscan Invocation
@section Using @command{autoscan} to Create @file{configure.ac}
@cindex @command{autoscan}
The @command{autoscan} program can help you create and/or maintain a
@file{configure.ac} file for a software package. @command{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.ac}
for that package, and checks a possibly existing @file{configure.ac} for
completeness.
When using @command{autoscan} to create a @file{configure.ac}, you
should manually examine @file{configure.scan} before renaming it to
@file{configure.ac}; it probably needs some adjustments.
Occasionally, @command{autoscan} outputs a macro in the wrong order
relative to another macro, so that @command{autoconf} produces a warning;
you need to move such macros manually. Also, if you want the package to
use a configuration header file, you must add a call to
@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
also have to change or add some @code{#if} directives to your program in
order to make it work with Autoconf (@pxref{ifnames Invocation}, for
information about a program that can help with that job).
When using @command{autoscan} to maintain a @file{configure.ac}, simply
consider adding its suggestions. The file @file{autoscan.log}
contains detailed information on why a macro is requested.
@command{autoscan} uses several data files (installed along with Autoconf)
to determine which macros to output when it finds particular symbols in
a package's source files. These data files all have the same format:
each line consists of a symbol, one or more blanks, and the Autoconf macro to
output if that symbol is encountered. Lines starting with @samp{#} are
comments.
@command{autoscan} accepts the following options:
@table @option
@item --help
@itemx -h
Print a summary of the command line options and exit.
@item --version
@itemx -V
Print the version number of Autoconf and exit.
@item --verbose
@itemx -v
Print the names of the files it examines and the potentially interesting
symbols it finds in them. This output can be voluminous.
@item --debug
@itemx -d
Don't remove temporary files.
@item --include=@var{dir}
@itemx -I @var{dir}
Append @var{dir} to the include path. Multiple invocations accumulate.
@item --prepend-include=@var{dir}
@itemx -B @var{dir}
Prepend @var{dir} to the include path. Multiple invocations accumulate.
@end table
@node ifnames Invocation
@section Using @command{ifnames} to List Conditionals
@cindex @command{ifnames}
@command{ifnames} can help you write @file{configure.ac} for a software
package. It prints the identifiers that the package already uses in C
preprocessor conditionals. If a package has already been set up to have
some portability, @command{ifnames} can thus help you figure out what its
@command{configure} needs to check for. It may help fill in some gaps in a
@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
Invocation}).
@command{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}, @code{#ifdef}, or @code{#ifndef}
directives. It prints each identifier on a line, followed by a
space-separated list of the files in which that identifier occurs.
@noindent
@command{ifnames} accepts the following options:
@table @option
@item --help
@itemx -h
Print a summary of the command line options and exit.
@item --version
@itemx -V
Print the version number of Autoconf and exit.
@end table
@node autoconf Invocation
@section Using @command{autoconf} to Create @command{configure}
@cindex @command{autoconf}
To create @command{configure} from @file{configure.ac}, run the
@command{autoconf} program with no arguments. @command{autoconf} processes
@file{configure.ac} with the M4 macro processor, using the
Autoconf macros. If you give @command{autoconf} an argument, it reads that
file instead of @file{configure.ac} and writes the configuration script
to the standard output instead of to @command{configure}. If you give
@command{autoconf} the argument @option{-}, it reads from the standard
input instead of @file{configure.ac} and writes the configuration script
to the standard output.
The Autoconf macros are defined in several files. Some of the files are
distributed with Autoconf; @command{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 Autoconf Macros}, for more information). If a macro is
defined in more than one of the files that @command{autoconf} reads, the
last definition it reads overrides the earlier ones.
@command{autoconf} accepts the following options:
@table @option
@item --help
@itemx -h
Print a summary of the command line options and exit.
@item --version
@itemx -V
Print the version number of Autoconf and exit.
@item --verbose
@itemx -v
Report processing steps.
@item --debug
@itemx -d
Don't remove the temporary files.
@item --force
@itemx -f
Remake @file{configure} even if newer than its input files.
@item --include=@var{dir}
@itemx -I @var{dir}
Append @var{dir} to the include path. Multiple invocations accumulate.
@item --prepend-include=@var{dir}
@itemx -B @var{dir}
Prepend @var{dir} to the include path. Multiple invocations accumulate.
@item --output=@var{file}
@itemx -o @var{file}
Save output (script or trace) to @var{file}. The file @option{-} stands
for the standard output.
@item --warnings=@var{category}
@itemx -W @var{category}
@evindex WARNINGS
Report the warnings related to @var{category} (which can actually be a
comma separated list). @xref{Reporting Messages}, macro
@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
values include:
@table @samp
@item all
report all the warnings
@item none
report none
@item error
treats warnings as errors
@item no-@var{category}
disable warnings falling into @var{category}
@end table
Warnings about @samp{syntax} are enabled by default, and the environment
variable @env{WARNINGS}, a comma separated list of categories, is
honored as well. Passing @option{-W @var{category}} actually behaves as if
you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To
disable the defaults and @env{WARNINGS}, and then
enable warnings about obsolete constructs, use @option{-W
none,obsolete}.
@cindex Back trace
@cindex Macro invocation stack
Because @command{autoconf} uses @command{autom4te} behind the scenes, it
displays a back trace for errors, but not for warnings; if you want
them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
examples.
@item --trace=@var{macro}[:@var{format}]
@itemx -t @var{macro}[:@var{format}]
Do not create the @command{configure} script, but list the calls to
@var{macro} according to the @var{format}. Multiple @option{--trace}
arguments can be used to list several macros. Multiple @option{--trace}
arguments for a single macro are not cumulative; instead, you should
just make @var{format} as long as needed.
The @var{format} is a regular string, with newlines if desired, and
several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
@ref{autom4te Invocation}, for details on the @var{format}.
@item --initialization
@itemx -i
By default, @option{--trace} does not trace the initialization of the
Autoconf macros (typically the @code{AC_DEFUN} definitions). This
results in a noticeable speedup, but can be disabled by this option.
@end table
It is often necessary to check the content of a @file{configure.ac}
file, but parsing it yourself is extremely fragile and error-prone. It
is suggested that you rely upon @option{--trace} to scan
@file{configure.ac}. For instance, to find the list of variables that
are substituted, use:
@example
@group
$ @kbd{autoconf -t AC_SUBST}
configure.ac:2:AC_SUBST:ECHO_C
configure.ac:2:AC_SUBST:ECHO_N
configure.ac:2:AC_SUBST:ECHO_T
@i{More traces deleted}
@end group
@end example
@noindent
The example below highlights the difference between @samp{$@@},
@samp{$*}, and @samp{$%}.
@example
@group
$ @kbd{cat configure.ac}
AC_DEFINE(This, is, [an
[example]])
$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
*: $*
%: $%'
@@: [This],[is],[an
[example]]
*: This,is,an
[example]
%: This:is:an [example]
@end group
@end example
@noindent
The @var{format} gives you a lot of freedom:
@example
@group
$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
$ac_subst@{"ECHO_C"@} = "configure.ac:2";
$ac_subst@{"ECHO_N"@} = "configure.ac:2";
$ac_subst@{"ECHO_T"@} = "configure.ac:2";
@i{More traces deleted}
@end group
@end example
@noindent
A long @var{separator} can be used to improve the readability of complex
structures, and to ease their parsing (for instance when no single
character is suitable as a separator):
@example
@group
$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
ACLOCAL|:::::|aclocal|:::::|$missing_dir
AUTOCONF|:::::|autoconf|:::::|$missing_dir
AUTOMAKE|:::::|automake|:::::|$missing_dir
@i{More traces deleted}
@end group
@end example
@node autoreconf Invocation
@section Using @command{autoreconf} to Update @command{configure} Scripts
@cindex @command{autoreconf}
Installing the various components of the GNU Build System can be
tedious: running @command{autopoint} for Gettext, @command{automake} for
@file{Makefile.in} etc.@: in each directory. It may be needed either
because some tools such as @command{automake} have been updated on your
system, or because some of the sources such as @file{configure.ac} have
been updated, or finally, simply in order to install the GNU Build
System in a fresh tree.
@command{autoreconf} runs @command{autoconf}, @command{autoheader},
@command{aclocal}, @command{automake}, @command{libtoolize}, and
@command{autopoint} (when appropriate) repeatedly to update the
GNU Build System in the specified directories and their
subdirectories (@pxref{Subdirectories}). By default, it only remakes
those files that are older than their sources. The environment variables
@env{AUTOM4TE}, @env{AUTOCONF}, @env{AUTOHEADER}, @env{AUTOMAKE},
@env{ACLOCAL}, @env{AUTOPOINT}, @env{LIBTOOLIZE}, @env{M4}, and @env{MAKE}
may be used to override the invocation of the respective tools.
If you install a new version of some tool, you can make
@command{autoreconf} remake @emph{all} of the files by giving it the
@option{--force} option.
@xref{Automatic Remaking}, for Make rules to automatically
rebuild @command{configure} scripts when their source files change. That
method handles the timestamps of configuration header templates
properly, but does not pass @option{--autoconf-dir=@var{dir}} or
@option{--localdir=@var{dir}}.
@cindex Gettext
@cindex @command{autopoint}
Gettext supplies the @command{autopoint} command to add translation
infrastructure to a source package. If you use @command{autopoint},
your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
@code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
Invocation, , Invoking the @code{autopoint} Program, gettext,
GNU @code{gettext} utilities}, for further details.
@noindent
@command{autoreconf} accepts the following options:
@table @option
@item --help
@itemx -h
Print a summary of the command line options and exit.
@item --version
@itemx -V
Print the version number of Autoconf and exit.
@item --verbose
@itemx -v
Print the name of each directory @command{autoreconf} examines and the
commands it runs. If given two or more times, pass @option{--verbose}
to subordinate tools that support it.
@item --debug
@itemx -d
Don't remove the temporary files.
@item --force
@itemx -f
Remake even @file{configure} scripts and configuration headers that are
newer than their input files (@file{configure.ac} and, if present,
@file{aclocal.m4}).
@item --install
@itemx -i
Install the missing auxiliary files in the package. By default, files
are copied; this can be changed with @option{--symlink}.
If deemed appropriate, this option triggers calls to
@samp{automake --add-missing},
@samp{libtoolize}, @samp{autopoint}, etc.
@item --no-recursive
Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
macro @code{AC_CONFIG_SUBDIRS}).
@item --symlink
@itemx -s
When used with @option{--install}, install symbolic links to the missing
auxiliary files instead of copying them.
@item --make
@itemx -m
When the directories were configured, update the configuration by
running @samp{./config.status --recheck && ./config.status}, and then
run @samp{make}.
@item --include=@var{dir}
@itemx -I @var{dir}
Append @var{dir} to the include path. Multiple invocations accumulate.
Passed on to @command{aclocal}, @command{autoconf} and
@command{autoheader} internally.
@item --prepend-include=@var{dir}
@itemx -B @var{dir}
Prepend @var{dir} to the include path. Multiple invocations accumulate.
Passed on to @command{autoconf} and @command{autoheader} internally.
@item --warnings=@var{category}
@itemx -W @var{category}
@evindex WARNINGS
Report the warnings related to @var{category} (which can actually be a
comma separated list).
@table @samp
@item cross
related to cross compilation issues.
@item obsolete
report the uses of obsolete constructs.
@item portability
portability issues
@item syntax
dubious syntactic constructs.
@item all
report all the warnings
@item none
report none
@item error
treats warnings as errors
@item no-@var{category}
disable warnings falling into @var{category}
@end table
Warnings about @samp{syntax} are enabled by default, and the environment
variable @env{WARNINGS}, a comma separated list of categories, is
honored as well. Passing @option{-W @var{category}} actually behaves as if
you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To
disable the defaults and @env{WARNINGS}, and then
enable warnings about obsolete constructs, use @option{-W
none,obsolete}.
@end table
If you want @command{autoreconf} to pass flags that are not listed here
on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
Due to a limitation in the Autoconf implementation these flags currently
must be set on a single line in @file{Makefile.am}, without any
backslash-newlines.
@c ========================================= Initialization and Output Files.
@node Setup
@chapter Initialization and Output Files
Autoconf-generated @command{configure} scripts need some information about
how to initialize, such as how to find the package's source files and
about the output files to produce. The following sections describe the
initialization and the creation of output files.
@menu
* Initializing configure:: Option processing etc.
* Versioning:: Dealing with Autoconf versions
* Notices:: Copyright, version numbers in @command{configure}
* Input:: Where Autoconf should find files
* Output:: Outputting results from the configuration
* Configuration Actions:: Preparing the output based on results
* Configuration Files:: Creating output files
* Makefile Substitutions:: Using output variables in makefiles
* Configuration Headers:: Creating a configuration header file
* Configuration Commands:: Running arbitrary instantiation commands
* Configuration Links:: Links depending on the configuration
* Subdirectories:: Configuring independent packages together
* Default Prefix:: Changing the default installation prefix
@end menu
@node Initializing configure
@section Initializing @command{configure}
Every @command{configure} script must call @code{AC_INIT} before doing
anything else that produces output. Calls to silent macros, such as
@code{AC_DEFUN}, may also occur prior to @code{AC_INIT}, although these
are generally used via @file{aclocal.m4}, since that is implicitly
included before the start of @file{configure.ac}. The only other
required macro is @code{AC_OUTPUT} (@pxref{Output}).
@anchor{AC_INIT}
@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @
@ovar{tarname}, @ovar{url})
@acindex{INIT}
Process any command-line arguments and perform initialization
and verification.
Set the name of the @var{package} and its @var{version}. These are
typically used in @option{--version} support, including that of
@command{configure}. The optional argument @var{bug-report} should be
the email to which users should send bug reports. The package
@var{tarname} differs from @var{package}: the latter designates the full
package name (e.g., @samp{GNU Autoconf}), while the former is meant for
distribution tar ball names (e.g., @samp{autoconf}). It defaults to
@var{package} with @samp{GNU } stripped, lower-cased, and all characters
other than alphanumerics and underscores are changed to @samp{-}. If
provided, @var{url} should be the home page for the package.
The arguments of @code{AC_INIT} must be static, i.e., there should not
be any shell computation, quotes, or newlines, but they can be computed
by M4. This is because the package information strings are expanded at
M4 time into several contexts, and must give the same text at shell time
whether used in single-quoted strings, double-quoted strings, quoted
here-documents, or unquoted here-documents. It is permissible to use
@code{m4_esyscmd} or @code{m4_esyscmd_s} for computing a version string
that changes with every commit to a version control system (in fact,
Autoconf does just that, for all builds of the development tree made
between releases).
The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
@code{PACKAGE_NAME}), are defined by @code{AC_INIT}:
@table @asis
@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
@acindex{PACKAGE_NAME}
@ovindex PACKAGE_NAME
@cvindex PACKAGE_NAME
Exactly @var{package}.
@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
@acindex{PACKAGE_TARNAME}
@ovindex PACKAGE_TARNAME
@cvindex PACKAGE_TARNAME
Exactly @var{tarname}, possibly generated from @var{package}.
@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
@acindex{PACKAGE_VERSION}
@ovindex PACKAGE_VERSION
@cvindex PACKAGE_VERSION
Exactly @var{version}.
@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
@acindex{PACKAGE_STRING}
@ovindex PACKAGE_STRING
@cvindex PACKAGE_STRING
Exactly @samp{@var{package} @var{version}}.
@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
@acindex{PACKAGE_BUGREPORT}
@ovindex PACKAGE_BUGREPORT
@cvindex PACKAGE_BUGREPORT
Exactly @var{bug-report}, if one was provided. Typically an email
address, or URL to a bug management web page.
@item @code{AC_PACKAGE_URL}, @code{PACKAGE_URL}
@acindex{PACKAGE_URL}
@ovindex PACKAGE_URL
@cvindex PACKAGE_URL
Exactly @var{url}, if one was provided. If @var{url} was empty, but
@var{package} begins with @samp{GNU }, then this defaults to
@samp{http://@/www.gnu.org/@/software/@/@var{tarname}/}, otherwise, no URL is
assumed.
@end table
@end defmac
If your @command{configure} script does its own option processing, it
should inspect @samp{$@@} or @samp{$*} immediately after calling
@code{AC_INIT}, because other Autoconf macros liberally use the
@command{set} command to process strings, and this has the side effect
of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
standard macros like @code{AC_ARG_ENABLE} instead of attempting to
implement your own option processing. @xref{Site Configuration}.
@node Versioning
@section Dealing with Autoconf versions
@cindex Autoconf version
@cindex version, Autoconf
The following optional macros can be used to help choose the minimum
version of Autoconf that can successfully compile a given
@file{configure.ac}.
@defmac AC_PREREQ (@var{version})
@acindex{PREREQ}
@cindex Version
Ensure that a recent enough version of Autoconf is being used. If the
version of Autoconf being used to create @command{configure} is
earlier than @var{version}, print an error message to the standard
error output and exit with failure (exit status is 63). For example:
@example
AC_PREREQ([@value{VERSION}])
@end example
This macro may be used before @code{AC_INIT}.
@end defmac
@defmac AC_AUTOCONF_VERSION
@acindex{AUTOCONF_VERSION}
This macro was introduced in Autoconf 2.62. It identifies the version
of Autoconf that is currently parsing the input file, in a format
suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in
other words, for this release of Autoconf, its value is
@samp{@value{VERSION}}. One potential use of this macro is for writing
conditional fallbacks based on when a feature was added to Autoconf,
rather than using @code{AC_PREREQ} to require the newer version of
Autoconf. However, remember that the Autoconf philosophy favors feature
checks over version checks.
You should not expand this macro directly; use
@samp{m4_defn([AC_AUTOCONF_VERSION])} instead. This is because some
users might
have a beta version of Autoconf installed, with arbitrary letters
included in its version string. This means it is possible for the
version string to contain the name of a defined macro, such that
expanding @code{AC_AUTOCONF_VERSION} would trigger the expansion of that
macro during rescanning, and change the version string to be different
than what you intended to check.
@end defmac
@node Notices
@section Notices in @command{configure}
@cindex Notices in @command{configure}
The following macros manage version numbers for @command{configure}
scripts. Using them is optional.
@defmac AC_COPYRIGHT (@var{copyright-notice})
@acindex{COPYRIGHT}
@cindex Copyright Notice
State that, in addition to the Free Software Foundation's copyright on
the Autoconf macros, parts of your @command{configure} are covered by the
@var{copyright-notice}.
The @var{copyright-notice} shows up in both the head of
@command{configure} and in @samp{configure --version}.
@end defmac
@defmac AC_REVISION (@var{revision-info})
@acindex{REVISION}
@cindex Revision
Copy revision stamp @var{revision-info} into the @command{configure}
script, with any dollar signs or double-quotes removed. This macro lets
you put a revision stamp from @file{configure.ac} into @command{configure}
without RCS or CVS changing it when you check in
@command{configure}. That way, you can determine easily which revision of
@file{configure.ac} a particular @command{configure} corresponds to.
For example, this line in @file{configure.ac}:
@c The @w prevents RCS from changing the example in the manual.
@example
AC_REVISION([@w{$}Revision: 1.30 $])
@end example
@noindent
produces this in @command{configure}:
@example
#!/bin/sh
# From configure.ac Revision: 1.30
@end example
@end defmac
@node Input
@section Finding @command{configure} Input
@anchor{AC_CONFIG_SRCDIR}
@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
@acindex{CONFIG_SRCDIR}
@var{unique-file-in-source-dir} is some file that is in the package's
source directory; @command{configure} checks for this file's existence to
make sure that the directory that it is told contains the source code in
fact does. Occasionally people accidentally specify the wrong directory
with @option{--srcdir}; this is a safety check. @xref{configure
Invocation}, for more information.
@end defmac
@c FIXME: Remove definitively once --install explained.
@c
@c Small packages may store all their macros in @code{aclocal.m4}. As the
@c set of macros grows, or for maintenance reasons, a maintainer may prefer
@c to split the macros in several files. In this case, Autoconf must be
@c told which files to load, and in which order.
@c
@c @defmac AC_INCLUDE (@var{file}@dots{})
@c @acindex{INCLUDE}
@c @c FIXME: There is no longer shell globbing.
@c Read the macro definitions that appear in the listed files. A list of
@c space-separated file names or shell globbing patterns is expected. The
@c files are read in the order they're listed.
@c
@c Because the order of definition of macros is important (only the last
@c definition of a macro is used), beware that it is @code{AC_INIT} that
@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
@c the latter case, non-macro lines from included files may end up in the
@c @file{configure} script, whereas in the former case, they'd be discarded
@c just like any text that appear before @code{AC_INIT}.
@c @end defmac
Packages that do manual configuration or use the @command{install} program
might need to tell @command{configure} where to find some other shell
scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
it looks are correct for most cases.
@defmac AC_CONFIG_AUX_DIR (@var{dir})
@acindex{CONFIG_AUX_DIR}
Use the auxiliary build tools (e.g., @file{install-sh},
@file{config.sub}, @file{config.guess}, Cygnus @command{configure},
Automake and Libtool scripts, etc.)@: 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. It checks for @file{install.sh} also, but that
name is obsolete because some @command{make} have a rule that creates
@file{install} from it if there is no makefile.
The auxiliary directory is commonly named @file{build-aux}.
If you need portability to DOS variants, do not name the
auxiliary directory @file{aux}. @xref{File System Conventions}.
@end defmac
@defmac AC_REQUIRE_AUX_FILE (@var{file})
@acindex{REQUIRE_AUX_FILE}
Declares that @var{file} is expected in the directory defined above. In
Autoconf proper, this macro does nothing: its sole purpose is to be
traced by third-party tools to produce a list of expected auxiliary
files. For instance it is called by macros like @code{AC_PROG_INSTALL}
(@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
(@pxref{Canonicalizing}) to register the auxiliary files they need.
@end defmac
Similarly, packages that use @command{aclocal} should declare where
local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
@defmac AC_CONFIG_MACRO_DIR (@var{dir})
@acindex{CONFIG_MACRO_DIR}
Specify @var{dir} as the location of additional local Autoconf macros.
This macro is intended for use by future versions of commands like
@command{autoreconf} that trace macro calls. It should be called
directly from @file{configure.ac} so that tools that install macros for
@command{aclocal} can find the macros' declarations.
Note that if you use @command{aclocal} from Automake to generate
@file{aclocal.m4}, you must also set @code{ACLOCAL_AMFLAGS = -I
@var{dir}} in your top-level @file{Makefile.am}. Due to a limitation in
the Autoconf implementation of @command{autoreconf}, these include
directives currently must be set on a single line in @file{Makefile.am},
without any backslash-newlines.
@end defmac
@node Output
@section Outputting Files
@cindex Outputting files
Every Autoconf script, e.g., @file{configure.ac}, should finish by
calling @code{AC_OUTPUT}. That is the macro that generates and runs
@file{config.status}, which in turn creates the makefiles and any
other files resulting from configuration. This is the only required
macro besides @code{AC_INIT} (@pxref{Input}).
@anchor{AC_OUTPUT}
@defmac AC_OUTPUT
@acindex{OUTPUT}
@cindex Instantiation
Generate @file{config.status} and launch it. Call this macro once, at
the end of @file{configure.ac}.
@file{config.status} performs all the configuration actions: all the
output files (see @ref{Configuration Files}, macro
@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
are honored.
The location of your @code{AC_OUTPUT} invocation is the exact point
where configuration actions are taken: any code afterwards is
executed by @command{configure} once @command{config.status} was run. If
you want to bind actions to @command{config.status} itself
(independently of whether @command{configure} is being run), see
@ref{Configuration Commands, , Running Arbitrary Configuration
Commands}.
@end defmac
Historically, the usage of @code{AC_OUTPUT} was somewhat different.
@xref{Obsolete Macros}, for a description of the arguments that
@code{AC_OUTPUT} used to support.
If you run @command{make} in subdirectories, you should run it using the
@command{make} variable @code{MAKE}. Most versions of @command{make} set
@code{MAKE} to the name of the @command{make} program plus any options it
was given. (But many do not include in it the values of any variables
set on the command line, so those are not passed on automatically.)
Some old versions of @command{make} do not set this variable. The
following macro allows you to use it even with those versions.
@anchor{AC_PROG_MAKE_SET}
@defmac AC_PROG_MAKE_SET
@acindex{PROG_MAKE_SET}
@ovindex SET_MAKE
If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
@code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
Otherwise, define @code{SET_MAKE} to a macro definition that sets
@code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
@code{SET_MAKE}.
@end defmac
If you use this macro, place a line like this in each @file{Makefile.in}
that runs @command{MAKE} on other directories:
@example
@@SET_MAKE@@
@end example
@node Configuration Actions
@section Performing Configuration Actions
@cindex Configuration actions
@file{configure} is designed so that it appears to do everything itself,
but there is actually a hidden slave: @file{config.status}.
@file{configure} is in charge of examining your system, but it is
@file{config.status} that actually takes the proper actions based on the
results of @file{configure}. The most typical task of
@file{config.status} is to @emph{instantiate} files.
@acindex{CONFIG_@var{ITEMS}}
This section describes the common behavior of the four standard
instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
have this prototype:
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
@c awful.
@example
AC_CONFIG_@var{ITEMS}(@var{tag}@dots{}, @r{[}@var{commands}@r{]}, @r{[}@var{init-cmds}@r{]})
@end example
@noindent
where the arguments are:
@table @var
@item tag@dots{}
A blank-or-newline-separated list of tags, which are typically the names of
the files to instantiate.
You are encouraged to use literals as @var{tags}. In particular, you
should avoid
@example
@dots{} && my_foos="$my_foos fooo"
@dots{} && my_foos="$my_foos foooo"
AC_CONFIG_@var{ITEMS}([$my_foos])
@end example
@noindent
and use this instead:
@example
@dots{} && AC_CONFIG_@var{ITEMS}([fooo])
@dots{} && AC_CONFIG_@var{ITEMS}([foooo])
@end example
The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
special @var{tag} values: they may have the form @samp{@var{output}} or
@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
@samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])},
for example, asks for
the creation of the file @file{Makefile} that contains the expansion of the
output variables in the concatenation of @file{boiler/top.mk} and
@file{boiler/bot.mk}.
The special value @samp{-} might be used to denote the standard output
when used in @var{output}, or the standard input when used in the
@var{inputs}. You most probably don't need to use this in
@file{configure.ac}, but it is convenient when using the command line
interface of @file{./config.status}, see @ref{config.status Invocation},
for more details.
The @var{inputs} may be absolute or relative file names. In the latter
case they are first looked for in the build tree, and then in the source
tree. Input files should be text files, and a line length below 2000
bytes should be safe.
@item commands
Shell commands output literally into @file{config.status}, and
associated with a tag that the user can use to tell @file{config.status}
which commands to run. The commands are run each time a @var{tag}
request is given to @file{config.status}, typically each time the file
@file{@var{tag}} is created.
The variables set during the execution of @command{configure} are
@emph{not} available here: you first need to set them via the
@var{init-cmds}. Nonetheless the following variables are precomputed:
@table @code
@item srcdir
@vrindex srcdir
The name of the top source directory, assuming that the working
directory is the top build directory. This
is what the @command{configure} option @option{--srcdir} sets.
@item ac_top_srcdir
@vrindex ac_top_srcdir
The name of the top source directory, assuming that the working
directory is the current build directory.
@item ac_top_build_prefix
@vrindex ac_top_build_prefix
The name of the top build directory, assuming that the working
directory is the current build directory.
It can be empty, or else ends with a slash, so that you may concatenate
it.
@item ac_srcdir
@vrindex ac_srcdir
The name of the corresponding source directory, assuming that the
working directory is the current build directory.
@item tmp
@vrindex tmp
The name of a temporary directory within the build tree, which you
can use if you need to create additional temporary files. The
directory is cleaned up when @command{config.status} is done or
interrupted. Please use package-specific file name prefixes to
avoid clashing with files that @command{config.status} may use
internally.
@end table
@noindent
The @dfn{current} directory refers to the directory (or
pseudo-directory) containing the input part of @var{tags}. For
instance, running
@example
AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
@end example
@noindent
with @option{--srcdir=../package} produces the following values:
@example
# Argument of --srcdir
srcdir='../package'
# Reversing deep/dir
ac_top_build_prefix='../../'
# Concatenation of $ac_top_build_prefix and srcdir
ac_top_srcdir='../../../package'
# Concatenation of $ac_top_srcdir and deep/dir
ac_srcdir='../../../package/deep/dir'
@end example
@noindent
independently of @samp{in/in.in}.
@item init-cmds
Shell commands output @emph{unquoted} near the beginning of
@file{config.status}, and executed each time @file{config.status} runs
(regardless of the tag). Because they are unquoted, for example,
@samp{$var} is output as the value of @code{var}. @var{init-cmds}
is typically used by @file{configure} to give @file{config.status} some
variables it needs to run the @var{commands}.
You should be extremely cautious in your variable names: all the
@var{init-cmds} share the same name space and may overwrite each other
in unpredictable ways. Sorry@enddots{}
@end table
All these macros can be called multiple times, with different
@var{tag} values, of course!
@node Configuration Files
@section Creating Configuration Files
@cindex Creating configuration files
@cindex Configuration file creation
Be sure to read the previous section, @ref{Configuration Actions}.
@anchor{AC_CONFIG_FILES}
@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
@acindex{CONFIG_FILES}
Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
file (by default @file{@var{file}.in}), substituting the output variable
values.
@c Before we used to have this feature, which was later rejected
@c because it complicates the writing of makefiles:
@c If the file would be unchanged, it is left untouched, to preserve
@c timestamp.
This macro is one of the instantiating macros; see @ref{Configuration
Actions}. @xref{Makefile Substitutions}, for more information on using
output variables. @xref{Setting Output Variables}, for more information
on creating them. This macro creates the directory that the file is in
if it doesn't exist. Usually, makefiles are created this way,
but other files, such as @file{.gdbinit}, can be specified as well.
Typical calls to @code{AC_CONFIG_FILES} look like this:
@example
AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
@end example
You can override an input file name by appending to @var{file} a
colon-separated list of input files. Examples:
@example
AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
[lib/Makefile:boiler/lib.mk])
@end example
@noindent
Doing this allows you to keep your file names acceptable to
DOS variants, or
to prepend and/or append boilerplate to the file.
@end defmac
@node Makefile Substitutions
@section Substitutions in Makefiles
@cindex Substitutions in makefiles
@cindex Makefile substitutions
Each subdirectory in a distribution that contains something to be
compiled or installed should come with a file @file{Makefile.in}, from
which @command{configure} creates a file @file{Makefile} in that directory.
To create @file{Makefile}, @command{configure} performs a simple variable
substitution, replacing occurrences of @samp{@@@var{variable}@@} in
@file{Makefile.in} with the value that @command{configure} has determined
for that variable. Variables that are substituted into output files in
this way are called @dfn{output variables}. They are ordinary shell
variables that are set in @command{configure}. To make @command{configure}
substitute a particular variable into the output files, the macro
@code{AC_SUBST} must be called with that variable name as an argument.
Any occurrences of @samp{@@@var{variable}@@} for other variables are
left unchanged. @xref{Setting Output Variables}, for more information
on creating output variables with @code{AC_SUBST}.
A software package that uses a @command{configure} script should be
distributed with a file @file{Makefile.in}, but no makefile; that
way, the user has to properly configure the package for the local system
before compiling it.
@xref{Makefile Conventions, , Makefile Conventions, standards, The
GNU Coding Standards}, for more information on what to put in
makefiles.
@menu
* Preset Output Variables:: Output variables that are always set
* Installation Directory Variables:: Other preset output variables
* Changed Directory Variables:: Warnings about @file{datarootdir}
* Build Directories:: Supporting multiple concurrent compiles
* Automatic Remaking:: Makefile rules for configuring
@end menu
@node Preset Output Variables
@subsection Preset Output Variables
@cindex Output variables
Some output variables are preset by the Autoconf macros. Some of the
Autoconf macros set additional output variables, which are mentioned in
the descriptions for those macros. @xref{Output Variable Index}, for a
complete list of output variables. @xref{Installation Directory
Variables}, for the list of the preset ones related to installation
directories. Below are listed the other preset ones, many of which are
precious variables (@pxref{Setting Output Variables},
@code{AC_ARG_VAR}).
The preset variables which are available during @file{config.status}
(@pxref{Configuration Actions}) may also be used during
@command{configure} tests. For example, it is permissible to reference
@samp{$srcdir} when constructing a list of directories to pass via
option @option{-I} during a compiler feature check. When used in this
manner, coupled with the fact that @command{configure} is always run
from the top build directory, it is sufficient to use just
@samp{$srcdir} instead of @samp{$top_srcdir}.
@c Just say no to ASCII sorting! We're humans, not computers.
@c These variables are listed as they would be in a dictionary:
@c actor
@c Actress
@c actress
@defvar CFLAGS
@evindex CFLAGS
@ovindex CFLAGS
Debugging and optimization options for the C compiler. If it is not set
in the environment when @command{configure} runs, the default value is set
when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
uses this variable when compiling or linking programs to test for C features.
If a compiler option affects only the behavior of the preprocessor
(e.g., @option{-D@var{name}}), it should be put into @code{CPPFLAGS}
instead. If it affects only the linker (e.g., @option{-L@var{directory}}),
it should be put into @code{LDFLAGS} instead. If it
affects only the compiler proper, @code{CFLAGS} is the natural home for
it. If an option affects multiple phases of the compiler, though,
matters get tricky. One approach to put such options directly into
@code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
@code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
However, remember that some @file{Makefile} variables are reserved by
the GNU Coding Standards for the use of the ``user''---the person
building the package. For instance, @code{CFLAGS} is one such variable.
Sometimes package developers are tempted to set user variables such as
@code{CFLAGS} because it appears to make their job easier. However, the
package itself should never set a user variable, particularly not to
include switches that are required for proper compilation of the
package. Since these variables are documented as being for the package
builder, that person rightfully expects to be able to override any of
these variables at build time. If the package developer needs to add
switches without interfering with the user, the proper way to do that is
to introduce an additional variable. Automake makes this easy by
introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , ,
automake, GNU Automake}), but the concept is the same even if
Automake is not used.
@end defvar
@defvar configure_input
@ovindex configure_input
A comment saying that the file was generated automatically by
@command{configure} and giving the name of the input file.
@code{AC_OUTPUT} adds a comment line containing this variable to the top
of every makefile it creates. For other files, you should
reference this variable in a comment at the top of each input file. For
example, an input shell script should begin like this:
@example
#!/bin/sh
# @@configure_input@@
@end example
@noindent
The presence of that line also reminds people editing the file that it
needs to be processed by @command{configure} in order to be used.
@end defvar
@defvar CPPFLAGS
@evindex CPPFLAGS
@ovindex CPPFLAGS
Preprocessor options for the C, C++, Objective C, and Objective C++
preprocessors and compilers. If
it is not set in the environment when @command{configure} runs, the default
value is empty. @command{configure} uses this variable when preprocessing
or compiling programs to test for C, C++, Objective C, and Objective C++
features.
This variable's contents should contain options like @option{-I},
@option{-D}, and @option{-U} that affect only the behavior of the
preprocessor. Please see the explanation of @code{CFLAGS} for what you
can do if an option affects other phases of the compiler as well.
Currently, @command{configure} always links as part of a single
invocation of the compiler that also preprocesses and compiles, so it
uses this variable also when linking programs. However, it is unwise to
depend on this behavior because the GNU Coding Standards do
not require it and many packages do not use @code{CPPFLAGS} when linking
programs.
@xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
might run into.
@end defvar
@defvar CXXFLAGS
@evindex CXXFLAGS
@ovindex CXXFLAGS
Debugging and optimization options for the C++ compiler. It acts like
@code{CFLAGS}, but for C++ instead of C.
@end defvar
@defvar DEFS
@ovindex DEFS
@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
is called, @command{configure} replaces @samp{@@DEFS@@} with
@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
variable is not defined while @command{configure} is performing its tests,
only when creating the output files. @xref{Setting Output Variables}, for
how to check the results of previous tests.
@end defvar
@defvar ECHO_C
@defvarx ECHO_N
@defvarx ECHO_T
@ovindex ECHO_C
@ovindex ECHO_N
@ovindex ECHO_T
How does one suppress the trailing newline from @command{echo} for
question-answer message pairs? These variables provide a way:
@example
echo $ECHO_N "And the winner is... $ECHO_C"
sleep 100000000000
echo "$@{ECHO_T@}dead."
@end example
@noindent
Some old and uncommon @command{echo} implementations offer no means to
achieve this, in which case @code{ECHO_T} is set to tab. You might not
want to use it.
@end defvar
@defvar ERLCFLAGS
@evindex ERLCFLAGS
@ovindex ERLCFLAGS
Debugging and optimization options for the Erlang compiler. If it is not set
in the environment when @command{configure} runs, the default value is empty.
@command{configure} uses this variable when compiling
programs to test for Erlang features.
@end defvar
@defvar FCFLAGS
@evindex FCFLAGS
@ovindex FCFLAGS
Debugging and optimization options for the Fortran compiler. If it
is not set in the environment when @command{configure} runs, the default
value is set when you call @code{AC_PROG_FC} (or empty if you don't).
@command{configure} uses this variable when compiling or linking
programs to test for Fortran features.
@end defvar
@defvar FFLAGS
@evindex FFLAGS
@ovindex FFLAGS
Debugging and optimization options for the Fortran 77 compiler. If it
is not set in the environment when @command{configure} runs, the default
value is set when you call @code{AC_PROG_F77} (or empty if you don't).
@command{configure} uses this variable when compiling or linking
programs to test for Fortran 77 features.
@end defvar
@defvar LDFLAGS
@evindex LDFLAGS
@ovindex LDFLAGS
Options for the linker. If it is not set
in the environment when @command{configure} runs, the default value is empty.
@command{configure} uses this variable when linking programs to test for
C, C++, Objective C, Objective C++, Fortran, and Go features.
This variable's contents should contain options like @option{-s} and
@option{-L} that affect only the behavior of the linker. Please see the
explanation of @code{CFLAGS} for what you can do if an option also
affects other phases of the compiler.
Don't use this variable to pass library names
(@option{-l}) to the linker; use @code{LIBS} instead.
@end defvar
@defvar LIBS
@evindex LIBS
@ovindex LIBS
@option{-l} options to pass to the linker. The default value is empty,
but some Autoconf macros may prepend extra libraries to this variable if
those libraries are found and provide necessary functions, see
@ref{Libraries}. @command{configure} uses this variable when linking
programs to test for C, C++, Objective C, Objective C++, Fortran, and Go
features.
@end defvar
@defvar OBJCFLAGS
@evindex OBJCFLAGS
@ovindex OBJCFLAGS
Debugging and optimization options for the Objective C compiler. It
acts like @code{CFLAGS}, but for Objective C instead of C.
@end defvar
@defvar OBJCXXFLAGS
@evindex OBJCXXFLAGS
@ovindex OBJCXXFLAGS
Debugging and optimization options for the Objective C++ compiler. It
acts like @code{CXXFLAGS}, but for Objective C++ instead of C++.
@end defvar
@defvar GOFLAGS
@evindex GOFLAGS
@ovindex GOFLAGS
Debugging and optimization options for the Go compiler. It acts like
@code{CFLAGS}, but for Go instead of C.
@end defvar
@defvar builddir
@ovindex builddir
Rigorously equal to @samp{.}. Added for symmetry only.
@end defvar
@defvar abs_builddir
@ovindex abs_builddir
Absolute name of @code{builddir}.
@end defvar
@defvar top_builddir
@ovindex top_builddir
The relative name of the top level of the current build tree. In the
top-level directory, this is the same as @code{builddir}.
@end defvar
@defvar top_build_prefix
@ovindex top_build_prefix
The relative name of the top level of the current build tree with final
slash if nonempty. This is the same as @code{top_builddir}, except that
it contains zero or more runs of @code{../}, so it should not be
appended with a slash for concatenation. This helps for @command{make}
implementations that otherwise do not treat @file{./file} and @file{file}
as equal in the toplevel build directory.
@end defvar
@defvar abs_top_builddir
@ovindex abs_top_builddir
Absolute name of @code{top_builddir}.
@end defvar
@defvar srcdir
@ovindex srcdir
The name of the directory that contains the source code for
that makefile.
@end defvar
@defvar abs_srcdir
@ovindex abs_srcdir
Absolute name of @code{srcdir}.
@end defvar
@defvar top_srcdir
@ovindex top_srcdir
The name of the top-level source code directory for the
package. In the top-level directory, this is the same as @code{srcdir}.
@end defvar
@defvar abs_top_srcdir
@ovindex abs_top_srcdir
Absolute name of @code{top_srcdir}.
@end defvar
@node Installation Directory Variables
@subsection Installation Directory Variables
@cindex Installation directories
@cindex Directories, installation
The following variables specify the directories for
package installation, see @ref{Directory Variables, , Variables for
Installation Directories, standards, The GNU Coding
Standards}, for more information. Each variable corresponds to an
argument of @command{configure}; trailing slashes are stripped so that
expressions such as @samp{$@{prefix@}/lib} expand with only one slash
between directory names. See the end of this section for
details on when and how to use these variables.
@defvar bindir
@ovindex bindir
The directory for installing executables that users run.
@end defvar
@defvar datadir
@ovindex datadir
The directory for installing idiosyncratic read-only
architecture-independent data.
@end defvar
@defvar datarootdir
@ovindex datarootdir
The root of the directory tree for read-only architecture-independent
data files.
@end defvar
@defvar docdir
@ovindex docdir
The directory for installing documentation files (other than Info and
man).
@end defvar
@defvar dvidir
@ovindex dvidir
The directory for installing documentation files in DVI format.
@end defvar
@defvar exec_prefix
@ovindex exec_prefix
The installation prefix for architecture-dependent files. By default
it's the same as @code{prefix}. You should avoid installing anything
directly to @code{exec_prefix}. However, the default value for
directories containing architecture-dependent files should be relative
to @code{exec_prefix}.
@end defvar
@defvar htmldir
@ovindex htmldir
The directory for installing HTML documentation.
@end defvar
@defvar includedir
@ovindex includedir
The directory for installing C header files.
@end defvar
@defvar infodir
@ovindex infodir
The directory for installing documentation in Info format.
@end defvar
@defvar libdir
@ovindex libdir
The directory for installing object code libraries.
@end defvar
@defvar libexecdir
@ovindex libexecdir
The directory for installing executables that other programs run.
@end defvar
@defvar localedir
@ovindex localedir
The directory for installing locale-dependent but
architecture-independent data, such as message catalogs. This directory
usually has a subdirectory per locale.
@end defvar
@defvar localstatedir
@ovindex localstatedir
The directory for installing modifiable single-machine data.
@end defvar
@defvar mandir
@ovindex mandir
The top-level directory for installing documentation in man format.
@end defvar
@defvar oldincludedir
@ovindex oldincludedir
The directory for installing C header files for non-GCC compilers.
@end defvar
@defvar pdfdir
@ovindex pdfdir
The directory for installing PDF documentation.
@end defvar
@defvar prefix
@ovindex prefix
The common installation prefix for all files. If @code{exec_prefix}
is defined to a different value, @code{prefix} is used only for
architecture-independent files.
@end defvar
@defvar psdir
@ovindex psdir
The directory for installing PostScript documentation.
@end defvar
@defvar sbindir
@ovindex sbindir
The directory for installing executables that system
administrators run.
@end defvar
@defvar sharedstatedir
@ovindex sharedstatedir
The directory for installing modifiable architecture-independent data.
@end defvar
@defvar sysconfdir
@ovindex sysconfdir
The directory for installing read-only single-machine data.
@end defvar
Most of these variables have values that rely on @code{prefix} or
@code{exec_prefix}. It is deliberate that the directory output
variables keep them unexpanded: typically @samp{@@datarootdir@@} is
replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
@samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
This behavior is mandated by the GNU Coding Standards, so that when
the user runs:
@table @samp
@item make
she can still specify a different prefix from the one specified to
@command{configure}, in which case, if needed, the package should hard
code dependencies corresponding to the make-specified prefix.
@item make install
she can specify a different installation location, in which case the
package @emph{must} still depend on the location which was compiled in
(i.e., never recompile when @samp{make install} is run). This is an
extremely important feature, as many people may decide to install all
the files of a package grouped together, and then install links from
the final locations to there.
@end table
In order to support these features, it is essential that
@code{datarootdir} remains defined as @samp{$@{prefix@}/share},
so that its value can be expanded based
on the current value of @code{prefix}.
A corollary is that you should not use these variables except in
makefiles. For instance, instead of trying to evaluate @code{datadir}
in @file{configure} and hard-coding it in makefiles using
e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
you should add
@option{-DDATADIR='$(datadir)'} to your makefile's definition of
@code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
@code{bindir} and friends in your shell scripts and other files; instead,
let @command{make} manage their replacement. For instance Autoconf
ships templates of its shell scripts ending with @samp{.in}, and uses a
makefile snippet similar to the following to build scripts like
@command{autoheader} and @command{autom4te}:
@example
@group
edit = sed \
-e 's|@@bindir[@@]|$(bindir)|g' \
-e 's|@@pkgdatadir[@@]|$(pkgdatadir)|g' \
-e 's|@@prefix[@@]|$(prefix)|g'
@end group
@group
autoheader autom4te: Makefile
rm -f $@@ $@@.tmp
srcdir=''; \
test -f ./$@@.in || srcdir=$(srcdir)/; \
$(edit) $$@{srcdir@}$@@.in >$@@.tmp
@c $$ restore font-lock
chmod +x $@@.tmp
chmod a-w $@@.tmp
mv $@@.tmp $@@
@end group
@group
autoheader: $(srcdir)/autoheader.in
autom4te: $(srcdir)/autom4te.in
@end group
@end example
Some details are noteworthy:
@table @asis
@item @samp{@@bindir[@@]}
The brackets prevent @command{configure} from replacing
@samp{@@bindir@@} in the Sed expression itself.
Brackets are preferable to a backslash here, since
Posix says @samp{\@@} is not portable.
@item @samp{$(bindir)}
Don't use @samp{@@bindir@@}! Use the matching makefile variable
instead.
@item @samp{$(pkgdatadir)}
The example takes advantage of the variable @samp{$(pkgdatadir)}
provided by Automake; it is equivalent to @samp{$(datadir)/$(PACKAGE)}.
@item @samp{/}
Don't use @samp{/} in the Sed expressions that replace file names since
most likely the
variables you use, such as @samp{$(bindir)}, contain @samp{/}.
Use a shell metacharacter instead, such as @samp{|}.
@item special characters
File names, file name components, and the value of @code{VPATH} should
not contain shell metacharacters or white
space. @xref{Special Chars in Variables}.
@item dependency on @file{Makefile}
Since @code{edit} uses values that depend on the configuration specific
values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
the output depends on @file{Makefile}, not @file{configure.ac}.
@item @samp{$@@}
The main rule is generic, and uses @samp{$@@} extensively to
avoid the need for multiple copies of the rule.
@item Separated dependencies and single suffix rules
You can't use them! The above snippet cannot be (portably) rewritten
as:
@example
autoconf autoheader: Makefile
@group
in:
rm -f $@@ $@@.tmp
$(edit) $< >$@@.tmp
chmod +x $@@.tmp
mv $@@.tmp $@@
@end group
@end example
@xref{Single Suffix Rules}, for details.
@item @samp{$(srcdir)}
Be sure to specify the name of the source directory,
otherwise the package won't support separated builds.
@end table
For the more specific installation of Erlang libraries, the following variables
are defined:
@defvar ERLANG_INSTALL_LIB_DIR
@ovindex ERLANG_INSTALL_LIB_DIR
@acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
The common parent directory of Erlang library installation directories.
This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
macro in @file{configure.ac}.
@end defvar
@defvar ERLANG_INSTALL_LIB_DIR_@var{library}
@ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
The installation directory for Erlang library @var{library}.
This variable is set by using the
@samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR}
macro in @file{configure.ac}.
@end defvar
@xref{Erlang Libraries}, for details.
@node Changed Directory Variables
@subsection Changed Directory Variables
@cindex @file{datarootdir}
In Autoconf 2.60, the set of directory variables has changed, and the
defaults of some variables have been adjusted
(@pxref{Installation Directory Variables}) to changes in the
GNU Coding Standards. Notably, @file{datadir}, @file{infodir}, and
@file{mandir} are now expressed in terms of @file{datarootdir}. If you are
upgrading from an earlier Autoconf version, you may need to adjust your files
to ensure that the directory variables are substituted correctly
(@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
in place. For example, in a @file{Makefile.in}, adding
@example
datarootdir = @@datarootdir@@
@end example
@noindent
is usually sufficient. If you use Automake to create @file{Makefile.in},
it will add this for you.
To help with the transition, Autoconf warns about files that seem to use
@code{datarootdir} without defining it. In some cases, it then expands
the value of @code{$datarootdir} in substitutions of the directory
variables. The following example shows such a warning:
@example
$ @kbd{cat configure.ac}
AC_INIT
AC_CONFIG_FILES([Makefile])
AC_OUTPUT
$ @kbd{cat Makefile.in}
prefix = @@prefix@@
datadir = @@datadir@@
$ @kbd{autoconf}
$ @kbd{configure}
configure: creating ./config.status
config.status: creating Makefile
config.status: WARNING:
Makefile.in seems to ignore the --datarootdir setting
$ @kbd{cat Makefile}
prefix = /usr/local
datadir = $@{prefix@}/share
@end example
Usually one can easily change the file to accommodate both older and newer
Autoconf releases:
@example
$ @kbd{cat Makefile.in}
prefix = @@prefix@@
datarootdir = @@datarootdir@@
datadir = @@datadir@@
$ @kbd{configure}
configure: creating ./config.status
config.status: creating Makefile
$ @kbd{cat Makefile}
prefix = /usr/local
datarootdir = $@{prefix@}/share
datadir = $@{datarootdir@}
@end example
@acindex{DATAROOTDIR_CHECKED}
In some cases, however, the checks may not be able to detect that a suitable
initialization of @code{datarootdir} is in place, or they may fail to detect
that such an initialization is necessary in the output file. If, after
auditing your package, there are still spurious @file{configure} warnings about
@code{datarootdir}, you may add the line
@example
AC_DEFUN([AC_DATAROOTDIR_CHECKED])
@end example
@noindent
to your @file{configure.ac} to disable the warnings. This is an exception
to the usual rule that you should not define a macro whose name begins with
@code{AC_} (@pxref{Macro Names}).
@node Build Directories
@subsection Build Directories
@cindex Build directories
@cindex Directories, build
You can support compiling a software package for several architectures
simultaneously from the same copy of the source code. The object files
for each architecture are kept in their own directory.
To support doing this, @command{make} uses the @code{VPATH} variable to
find the files that are in the source directory. GNU Make
can do this. Most other recent @command{make} programs can do this as
well, though they may have difficulties and it is often simpler to
recommend GNU @command{make} (@pxref{VPATH and Make}). Older
@command{make} programs do not support @code{VPATH}; when using them, the
source code must be in the same directory as the object files.
If you are using GNU Automake, the remaining details in this
section are already covered for you, based on the contents of your
@file{Makefile.am}. But if you are using Autoconf in isolation, then
supporting @code{VPATH} requires the following in your
@file{Makefile.in}:
@example
srcdir = @@srcdir@@
VPATH = @@srcdir@@
@end example
Do not set @code{VPATH} to the value of another variable (@pxref{Variables
listed in VPATH}.
@command{configure} substitutes the correct value for @code{srcdir} when
it produces @file{Makefile}.
Do not use the @command{make} variable @code{$<}, which expands to the
file name 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 @command{make} do not set @code{$<} in explicit rules; they
expand it to an empty value.
Instead, Make 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
@subsection Automatic Remaking
@cindex Automatic remaking
@cindex Remaking automatically
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 for
any of these files that your package does not use.
The @samp{$(srcdir)/} prefix is included because of limitations in the
@code{VPATH} mechanism.
The @file{stamp-} files are necessary because the timestamps of
@file{config.h.in} and @file{config.h} are not changed if remaking
them does not change their contents. This feature avoids unnecessary
recompilation. You should include the file @file{stamp-h.in} in your
package's distribution, so that @command{make} considers
@file{config.h.in} up to date. Don't use @command{touch}
(@pxref{touch, , Limitations of Usual Tools}); instead, use
@command{echo} (using
@command{date} would cause needless differences, hence CVS
conflicts, etc.).
@example
@group
$(srcdir)/configure: configure.ac aclocal.m4
cd '$(srcdir)' && autoconf
# autoheader might not change config.h.in, so touch a stamp file.
$(srcdir)/config.h.in: stamp-h.in
$(srcdir)/stamp-h.in: configure.ac aclocal.m4
cd '$(srcdir)' && autoheader
echo timestamp > '$(srcdir)/stamp-h.in'
config.h: stamp-h
stamp-h: config.h.in config.status
./config.status
Makefile: Makefile.in config.status
./config.status
config.status: configure
./config.status --recheck
@end group
@end example
@noindent
(Be careful if you copy these lines directly into your makefile, as you
need to convert the indented lines to start with the tab character.)
In addition, you should use
@example
AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
@end example
@noindent
so @file{config.status} ensures that @file{config.h} is considered up to
date. @xref{Output}, for more information about @code{AC_OUTPUT}.
@xref{config.status Invocation}, for more examples of handling
configuration-related dependencies.
@node Configuration Headers
@section Configuration Header Files
@cindex Configuration Header
@cindex @file{config.h}
When a package contains more than a few tests that define C preprocessor
symbols, the command lines to pass @option{-D} options to the compiler
can get quite long. This causes two problems. One is that the
@command{make} output is hard to visually scan for errors. More
seriously, the command lines can exceed the length limits of some
operating systems. As an alternative to passing @option{-D} options to
the compiler, @command{configure} scripts can create a C header file
containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
macro selects this kind of output. Though it can be called anywhere
between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
it right after @code{AC_INIT}.
The package should @samp{#include} the configuration header file before
any other header files, to prevent inconsistencies in declarations (for
example, if it redefines @code{const}).
To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
option (or @option{-I..}; whichever directory contains @file{config.h}).
Even if you use @samp{#include "config.h"}, the preprocessor searches only
the directory of the currently read file, i.e., the source directory, not
the build directory.
With the appropriate @option{-I} option, you can use
@samp{#include <config.h>}. Actually, it's a good habit to use it,
because in the rare case when the source directory contains another
@file{config.h}, the build directory should be searched first.
@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
@acindex{CONFIG_HEADERS}
@cvindex HAVE_CONFIG_H
This macro is one of the instantiating macros; see @ref{Configuration
Actions}. Make @code{AC_OUTPUT} create the file(s) in the
blank-or-newline-separated list @var{header} containing C preprocessor
@code{#define} statements, and replace @samp{@@DEFS@@} in generated
files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
The usual name for @var{header} is @file{config.h}.
If @var{header} already exists and its contents are identical to what
@code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
making some changes in the configuration without needlessly causing
object files that depend on the header file to be recompiled.
Usually the input file is named @file{@var{header}.in}; however, you can
override the input file name by appending to @var{header} a
colon-separated list of input files. For example, you might need to make
the input file name acceptable to DOS variants:
@example
AC_CONFIG_HEADERS([config.h:config.hin])
@end example
@end defmac
@defmac AH_HEADER
@ahindex{HEADER}
This macro is defined as the name of the first declared config header
and undefined if no config headers have been declared up to this point.
A third-party macro may, for example, require use of a config header
without invoking AC_CONFIG_HEADERS twice, like this:
@example
AC_CONFIG_COMMANDS_PRE(
[m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
@end example
@end defmac
@xref{Configuration Actions}, for more details on @var{header}.
@menu
* Header Templates:: Input for the configuration headers
* autoheader Invocation:: How to create configuration templates
* Autoheader Macros:: How to specify CPP templates
@end menu
@node Header Templates
@subsection Configuration Header Templates
@cindex Configuration Header Template
@cindex Header templates
@cindex @file{config.h.in}
Your distribution should contain a template file that looks as you want
the final header file to look, including comments, with @code{#undef}
statements which are used as hooks. For example, suppose your
@file{configure.ac} makes these calls:
@example
AC_CONFIG_HEADERS([conf.h])
AC_CHECK_HEADERS([unistd.h])
@end example
@noindent
Then you could have code like the following in @file{conf.h.in}.
The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H}
to 1, if and only if the system has @file{unistd.h}.
@example
@group
/* Define as 1 if you have unistd.h. */
#undef HAVE_UNISTD_H
@end group
@end example
The format of the template file is stricter than what the C preprocessor
is required to accept. A directive line should contain only whitespace,
@samp{#undef}, and @samp{HAVE_UNISTD_H}. The use of @samp{#define}
instead of @samp{#undef}, or of comments on the same line as
@samp{#undef}, is strongly discouraged. Each hook should only be listed
once. Other preprocessor lines, such as @samp{#ifdef} or
@samp{#include}, are copied verbatim from the template into the
generated header.
Since it is a tedious task to keep a template header up to date, you may
use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
During the instantiation of the header, each @samp{#undef} line in the
template file for each symbol defined by @samp{AC_DEFINE} is changed to an
appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not
been executed during the @command{configure} run, the @samp{#undef} line is
commented out. (This is important, e.g., for @samp{_POSIX_SOURCE}:
on many systems, it can be implicitly defined by the compiler, and
undefining it in the header would then break compilation of subsequent
headers.)
Currently, @emph{all} remaining @samp{#undef} lines in the header
template are commented out, whether or not there was a corresponding
@samp{AC_DEFINE} for the macro name; but this behavior is not guaranteed
for future releases of Autoconf.
Generally speaking, since you should not use @samp{#define}, and you
cannot guarantee whether a @samp{#undef} directive in the header
template will be converted to a @samp{#define} or commented out in the
generated header file, the template file cannot be used for conditional
definition effects. Consequently, if you need to use the construct
@example
@group
#ifdef THIS
# define THAT
#endif
@end group
@end example
@noindent
you must place it outside of the template.
If you absolutely need to hook it to the config header itself, please put
the directives to a separate file, and @samp{#include} that file from the
config header template. If you are using @command{autoheader}, you would
probably use @samp{AH_BOTTOM} to append the @samp{#include} directive.
@node autoheader Invocation
@subsection Using @command{autoheader} to Create @file{config.h.in}
@cindex @command{autoheader}
The @command{autoheader} program can create a template file of C
@samp{#define} statements for @command{configure} to use.
It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
@file{configure} sources to determine the name of the template.
(If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
input file name, @command{autoheader} uses the first one.)
It is recommended that only one input file is used. If you want to append
a boilerplate code, it is preferable to use
@samp{AH_BOTTOM([#include <conf_post.h>])}.
File @file{conf_post.h} is not processed during the configuration then,
which make things clearer. Analogically, @code{AH_TOP} can be used to
prepend a boilerplate code.
In order to do its job, @command{autoheader} needs you to document all
of the symbols that you might use. Typically this is done via an
@code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
is a literal symbol and whose third argument describes the symbol
(@pxref{Defining Symbols}). Alternatively, you can use
@code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
suitable input file for a subsequent configuration header file.
Symbols defined by Autoconf's builtin tests are already documented properly;
you need to document only those that you
define yourself.
You might wonder why @command{autoheader} is needed: after all, why
would @command{configure} need to ``patch'' a @file{config.h.in} to
produce a @file{config.h} instead of just creating @file{config.h} from
scratch? Well, when everything rocks, the answer is just that we are
wasting our time maintaining @command{autoheader}: generating
@file{config.h} directly is all that is needed. When things go wrong,
however, you'll be thankful for the existence of @command{autoheader}.
The fact that the symbols are documented is important in order to
@emph{check} that @file{config.h} makes sense. The fact that there is a
well-defined list of symbols that should be defined (or not) is
also important for people who are porting packages to environments where
@command{configure} cannot be run: they just have to @emph{fill in the
blanks}.
But let's come back to the point: the invocation of @command{autoheader}@dots{}
If you give @command{autoheader} an argument, it uses that file instead
of @file{configure.ac} and writes the header file to the standard output
instead of to @file{config.h.in}. If you give @command{autoheader} an
argument of @option{-}, it reads the standard input instead of
@file{configure.ac} and writes the header file to the standard output.
@command{autoheader} accepts the following options:
@table @option
@item --help
@itemx -h
Print a summary of the command line options and exit.
@item --version
@itemx -V
Print the version number of Autoconf and exit.
@item --verbose
@itemx -v
Report processing steps.
@item --debug
@itemx -d
Don't remove the temporary files.
@item --force
@itemx -f
Remake the template file even if newer than its input files.
@item --include=@var{dir}
@itemx -I @var{dir}
Append @var{dir} to the include path. Multiple invocations accumulate.
@item --prepend-include=@var{dir}
@itemx -B @var{dir}
Prepend @var{dir} to the include path. Multiple invocations accumulate.
@item --warnings=@var{category}
@itemx -W @var{category}
@evindex WARNINGS
Report the warnings related to @var{category} (which can actually be a
comma separated list). Current categories include:
@table @samp
@item obsolete
report the uses of obsolete constructs
@item all
report all the warnings
@item none
report none
@item error
treats warnings as errors
@item no-@var{category}
disable warnings falling into @var{category}
@end table
@end table
@node Autoheader Macros
@subsection Autoheader Macros
@cindex Autoheader macros
@command{autoheader} scans @file{configure.ac} and figures out which C
preprocessor symbols it might define. It knows how to generate
templates for symbols defined by @code{AC_CHECK_HEADERS},
@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
symbol, you must define a template for it. If there are missing
templates, @command{autoheader} fails with an error message.
The template for a @var{symbol} is created
by @command{autoheader} from
the @var{description} argument to an @code{AC_DEFINE};
see @ref{Defining Symbols}.
For special needs, you can use the following macros.
@defmac AH_TEMPLATE (@var{key}, @var{description})
@ahindex{TEMPLATE}
Tell @command{autoheader} to generate a template for @var{key}. This macro
generates standard templates just like @code{AC_DEFINE} when a
@var{description} is given.
For example:
@example
AH_TEMPLATE([CRAY_STACKSEG_END],
[Define to one of _getb67, GETB67, getb67
for Cray-2 and Cray-YMP systems. This
function is required for alloca.c support
on those systems.])
@end example
@noindent
generates the following template, with the description properly
justified.
@example
/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
Cray-YMP systems. This function is required for alloca.c
support on those systems. */
#undef CRAY_STACKSEG_END
@end example
@end defmac
@defmac AH_VERBATIM (@var{key}, @var{template})
@ahindex{VERBATIM}
Tell @command{autoheader} to include the @var{template} as-is in the header
template file. This @var{template} is associated with the @var{key},
which is used to sort all the different templates and guarantee their
uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
@end defmac
@defmac AH_TOP (@var{text})
@ahindex{TOP}
Include @var{text} at the top of the header template file.
@end defmac
@defmac AH_BOTTOM (@var{text})
@ahindex{BOTTOM}
Include @var{text} at the bottom of the header template file.
@end defmac
Please note that @var{text} gets included ``verbatim'' to the template file,
not to the resulting config header, so it can easily get mangled when the
template is processed. There is rarely a need for something other than
@example
AH_BOTTOM([#include <custom.h>])
@end example
@node Configuration Commands
@section Running Arbitrary Configuration Commands
@cindex Configuration commands
@cindex Commands for configuration
You can execute arbitrary commands before, during, and after
@file{config.status} is run. The three following macros accumulate the
commands to run when they are called multiple times.
@code{AC_CONFIG_COMMANDS} replaces the obsolete macro
@code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
@anchor{AC_CONFIG_COMMANDS}
@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
@acindex{CONFIG_COMMANDS}
Specify additional shell commands to run at the end of
@file{config.status}, and shell commands to initialize any variables
from @command{configure}. Associate the commands with @var{tag}.
Since typically the @var{cmds} create a file, @var{tag} should
naturally be the name of that file. If needed, the directory hosting
@var{tag} is created. This macro is one of the instantiating macros;
see @ref{Configuration Actions}.
Here is an unrealistic example:
@example
fubar=42
AC_CONFIG_COMMANDS([fubar],
[echo this is extra $fubar, and so on.],
[fubar=$fubar])
@end example
Here is a better one:
@example
AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
@end example
@end defmac
The following two macros look similar, but in fact they are not of the same
breed: they are executed directly by @file{configure}, so you cannot use
@file{config.status} to rerun them.
@c Yet it is good to leave them here. The user sees them together and
@c decides which best fits their needs.
@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
@acindex{CONFIG_COMMANDS_PRE}
Execute the @var{cmds} right before creating @file{config.status}.
This macro presents the last opportunity to call @code{AC_SUBST},
@code{AC_DEFINE}, or @code{AC_CONFIG_@var{ITEMS}} macros.
@end defmac
@defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
@acindex{CONFIG_COMMANDS_POST}
Execute the @var{cmds} right after creating @file{config.status}.
@end defmac
@node Configuration Links
@section Creating Configuration Links
@cindex Configuration links
@cindex Links for configuration
You may find it convenient to create links whose destinations depend upon
results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
creation of relative symbolic links can be delicate when the package is
built in a directory different from the source directory.
@anchor{AC_CONFIG_LINKS}
@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @
@ovar{init-cmds})
@acindex{CONFIG_LINKS}
@cindex Links
Make @code{AC_OUTPUT} 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 if possible, otherwise a copy. The
@var{dest} and @var{source} names should be relative to the top level
source or build directory. This macro is one of the instantiating
macros; see @ref{Configuration Actions}.
For example, this call:
@example
AC_CONFIG_LINKS([host.h:config/$machine.h
object.h:config/$obj_format.h])
@end example
@noindent
creates in the current directory @file{host.h} as a link to
@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
link to @file{@var{srcdir}/config/$obj_format.h}.
The tempting value @samp{.} for @var{dest} is invalid: it makes it
impossible for @samp{config.status} to guess the links to establish.
One can then run:
@example
/config.status host.h object.h
@end example
@noindent
to create the links.
@end defmac
@node Subdirectories
@section Configuring Other Packages in Subdirectories
@cindex Configure subdirectories
@cindex Subdirectory configure
In most situations, calling @code{AC_OUTPUT} is sufficient to produce
makefiles in subdirectories. However, @command{configure} scripts
that control more than one independent package can use
@code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
packages in subdirectories.
@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
@acindex{CONFIG_SUBDIRS}
@ovindex subdirs
Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
@var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
be a literal, i.e., please do not use:
@example
@c If you change this example, adjust tests/torture.at:Non-literal AC_CONFIG_SUBDIRS.
if test "x$package_foo_enabled" = xyes; then
my_subdirs="$my_subdirs foo"
fi
AC_CONFIG_SUBDIRS([$my_subdirs])
@end example
@noindent
because this prevents @samp{./configure --help=recursive} from
displaying the options of the package @code{foo}. Instead, you should
write:
@example
if test "x$package_foo_enabled" = xyes; then
AC_CONFIG_SUBDIRS([foo])
fi
@end example
If a given @var{dir} is not found at @command{configure} run time, a
warning is reported; if the subdirectory is optional, write:
@example
if test -d "$srcdir/foo"; then
AC_CONFIG_SUBDIRS([foo])
fi
@end example
@c NB: Yes, below we mean configure.in, not configure.ac.
If a given @var{dir} contains @command{configure.gnu}, it is run instead
of @command{configure}. This is for packages that might use a
non-Autoconf script @command{Configure}, which can't be called through a
wrapper @command{configure} since it would be the same file on
case-insensitive file systems. Likewise, if a @var{dir} contains
@file{configure.in} but no @command{configure}, the Cygnus
@command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
The subdirectory @command{configure} scripts are given the same command
line options that were given to this @command{configure} script, with minor
changes if needed, which include:
@itemize @minus
@item
adjusting a relative name for the cache file;
@item
adjusting a relative name for the source directory;
@item
propagating the current value of @code{$prefix}, including if it was
defaulted, and if the default values of the top level and of the subdirectory
@file{configure} differ.
@end itemize
This macro also sets the output variable @code{subdirs} to the list of
directories @samp{@var{dir} @dots{}}. Make rules can use
this variable to determine which subdirectories to recurse into.
This macro may be called multiple times.
@end defmac
@node Default Prefix
@section Default Prefix
@cindex Install prefix
@cindex Prefix for install
By default, @command{configure} sets the prefix for files it installs to
@file{/usr/local}. The user of @command{configure} can select a different
prefix using the @option{--prefix} and @option{--exec-prefix} options.
There are two ways to change the default: when creating
@command{configure}, and when running it.
Some software packages might want to install in a directory other than
@file{/usr/local} by default. To accomplish that, use the
@code{AC_PREFIX_DEFAULT} macro.
@defmac AC_PREFIX_DEFAULT (@var{prefix})
@acindex{PREFIX_DEFAULT}
Set the default installation prefix to @var{prefix} instead of
@file{/usr/local}.
@end defmac
It may be convenient for users to have @command{configure} guess the
installation prefix from the location of a related program that they
have already installed. If you wish to do that, you can call
@code{AC_PREFIX_PROGRAM}.
@anchor{AC_PREFIX_PROGRAM}
@defmac AC_PREFIX_PROGRAM (@var{program})
@acindex{PREFIX_PROGRAM}
If the user did not specify an installation prefix (using the
@option{--prefix} option), guess a value for it by looking for
@var{program} in @env{PATH}, the way the shell does. If @var{program}
is found, set the prefix to the parent of the directory containing
@var{program}, else default the prefix as described above
(@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
@var{program} is @code{gcc} and the @env{PATH} contains
@file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
@end defmac
@c ======================================================== Existing tests
@node Existing Tests
@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{Writing
Tests}).
These tests print messages telling the user which feature they're
checking for, and what they find. They cache their results for future
@command{configure} runs (@pxref{Caching Results}).
Some of these macros set output variables. @xref{Makefile
Substitutions}, for how to get their values. The phrase ``define
@var{name}'' is used below as a shorthand to mean ``define the C
preprocessor symbol @var{name} to the value 1''. @xref{Defining
Symbols}, for how to get those symbol definitions into your program.
@menu
* Common Behavior:: Macros' standard schemes
* Alternative Programs:: Selecting between alternative programs
* Files:: Checking for the existence of files
* Libraries:: Library archives that might be missing
* Library Functions:: C library functions that might be missing
* Header Files:: Header files that might be missing
* Declarations:: Declarations that may be missing
* Structures:: Structures or members that might be missing
* Types:: Types that might be missing
* Compilers and Preprocessors:: Checking for compiling programs
* System Services:: Operating system services
* Posix Variants:: Special kludges for specific Posix variants
* Erlang Libraries:: Checking for the existence of Erlang libraries
@end menu
@node Common Behavior
@section Common Behavior
@cindex Common autoconf behavior
Much effort has been expended to make Autoconf easy to learn. The most
obvious way to reach this goal is simply to enforce standard interfaces
and behaviors, avoiding exceptions as much as possible. Because of
history and inertia, unfortunately, there are still too many exceptions
in Autoconf; nevertheless, this section describes some of the common
rules.
@menu
* Standard Symbols:: Symbols defined by the macros
* Default Includes:: Includes used by the generic macros
@end menu
@node Standard Symbols
@subsection Standard Symbols
@cindex Standard symbols
All the generic macros that @code{AC_DEFINE} a symbol as a result of
their test transform their @var{argument} values to a standard alphabet.
First, @var{argument} is converted to upper case and any asterisks
(@samp{*}) are each converted to @samp{P}. Any remaining characters
that are not alphanumeric are converted to underscores.
For instance,
@example
AC_CHECK_TYPES([struct $Expensive*])
@end example
@noindent
defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
succeeds.
@node Default Includes
@subsection Default Includes
@cindex Default includes
@cindex Includes, default
Several tests depend upon a set of header files. Since these headers
are not universally available, tests actually have to provide a set of
protected includes, such as:
@example
@group
#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 group
@end example
@noindent
Unless you know exactly what you are doing, you should avoid using
unconditional includes, and check the existence of the headers you
include beforehand (@pxref{Header Files}).
Most generic macros use the following macro to provide the default set
of includes:
@defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
@acindex{INCLUDES_DEFAULT}
Expand to @var{include-directives} if defined, otherwise to:
@example
@group
#include <stdio.h>
#ifdef HAVE_SYS_TYPES_H
# include <sys/types.h>
#endif
#ifdef HAVE_SYS_STAT_H
# include <sys/stat.h>
#endif
#ifdef STDC_HEADERS
# include <stdlib.h>
# include <stddef.h>
#else
# ifdef HAVE_STDLIB_H
# include <stdlib.h>
# endif
#endif
#ifdef HAVE_STRING_H
# if !defined STDC_HEADERS && defined HAVE_MEMORY_H
# include <memory.h>
# endif
# include <string.h>
#endif
#ifdef HAVE_STRINGS_H
# include <strings.h>
#endif
#ifdef HAVE_INTTYPES_H
# include <inttypes.h>
#endif
#ifdef HAVE_STDINT_H
# include <stdint.h>
#endif
#ifdef HAVE_UNISTD_H
# include <unistd.h>
#endif
@end group
@end example
If the default includes are used, then check for the presence of these
headers and their compatibility, i.e., you don't need to run
@code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
These headers are checked for in the same order as they are included.
For instance, on some systems @file{string.h} and @file{strings.h} both
exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
@code{HAVE_STRINGS_H}.
@end defmac
@node Alternative Programs
@section Alternative Programs
@cindex Programs, checking
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
@subsection Particular Program Checks
These macros check for particular programs---whether they exist, and
in some cases whether they support certain features.
@defmac AC_PROG_AWK
@acindex{PROG_AWK}
@ovindex AWK
@caindex prog_AWK
Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
order, and set output variable @code{AWK} to the first one that is found.
It tries @code{gawk} first because that is reported to be the
best implementation. The result can be overridden by setting the
variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}.
Using this macro is sufficient to avoid the pitfalls of traditional
@command{awk} (@pxref{awk, , Limitations of Usual Tools}).
@end defmac
@defmac AC_PROG_GREP
@acindex{PROG_GREP}
@ovindex GREP
@caindex prog_GREP
Look for the best available @code{grep} or @code{ggrep} that accepts the
longest input lines possible, and that supports multiple @option{-e} options.
Set the output variable @code{GREP} to whatever is chosen.
@xref{grep, , Limitations of Usual Tools}, for more information about
portability problems with the @command{grep} command family. The result
can be overridden by setting the @code{GREP} variable and is cached in the
@code{ac_cv_path_GREP} variable.
@end defmac
@defmac AC_PROG_EGREP
@acindex{PROG_EGREP}
@ovindex EGREP
@caindex prog_EGREP
Check whether @code{$GREP -E} works, or else look for the best available
@code{egrep} or @code{gegrep} that accepts the longest input lines possible.
Set the output variable @code{EGREP} to whatever is chosen. The result
can be overridden by setting the @code{EGREP} variable and is cached in the
@code{ac_cv_path_EGREP} variable.
@end defmac
@defmac AC_PROG_FGREP
@acindex{PROG_FGREP}
@ovindex FGREP
@caindex prog_FGREP
Check whether @code{$GREP -F} works, or else look for the best available
@code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
Set the output variable @code{FGREP} to whatever is chosen. The result
can be overridden by setting the @code{FGREP} variable and is cached in the
@code{ac_cv_path_FGREP} variable.
@end defmac
@defmac AC_PROG_INSTALL
@acindex{PROG_INSTALL}
@ovindex INSTALL
@ovindex INSTALL_PROGRAM
@ovindex INSTALL_DATA
@ovindex INSTALL_SCRIPT
@caindex path_install
Set output variable @code{INSTALL} to the name of a BSD-compatible
@command{install} program, if one is found in the current @env{PATH}.
Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
default directories) to determine @var{dir} (@pxref{Output}). Also set
the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
@samp{@@INSTALL@@} is special, as its value may vary for different
configuration files.
This macro screens out various instances of @command{install} known not to
work. It prefers to find a C program rather than a shell script, for
speed. Instead of @file{install-sh}, it can also use @file{install.sh},
but that name is obsolete because some @command{make} programs have a rule
that creates @file{install} from it if there is no makefile. Further, this
macro requires @command{install} to be able to install multiple files into a
target directory in a single invocation.
Autoconf comes with a copy of @file{install-sh} that you can use. If
you use @code{AC_PROG_INSTALL}, you must include either
@file{install-sh} or @file{install.sh} in your distribution; otherwise
@command{configure} produces an error message saying it can't find
them---even if the system you're on has a good @command{install} program.
This check is a safety measure to prevent you from accidentally leaving
that file out, which would prevent your package from installing on
systems that don't have a BSD-compatible @command{install} program.
If you need to use your own installation program because it has features
not found in standard @command{install} programs, there is no reason to use
@code{AC_PROG_INSTALL}; just put the file name of your program into your
@file{Makefile.in} files.
The result of the test can be overridden by setting the variable
@code{INSTALL} or the cache variable @code{ac_cv_path_install}.
@end defmac
@defmac AC_PROG_MKDIR_P
@acindex{PROG_MKDIR_P}
@ovindex MKDIR_P
@caindex path_mkdir
Set output variable @code{MKDIR_P} to a program that ensures that for
each argument, a directory named by this argument exists, creating it
and its parent directories if needed, and without race conditions when
two instances of the program attempt to make the same directory at
nearly the same time.
This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
falls back on invoking @command{install-sh} with the @option{-d} option,
so your package should
contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
is vulnerable to race conditions, so if you want to support parallel
installs from
different packages into the same directory you need to make sure you
have an up-to-date @file{install-sh}. In particular, be careful about
using @samp{autoreconf -if} if your Automake predates Automake 1.10.
This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
in M4sh}), but it sets an output variable intended for use in other
files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
@command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
directory, and conversely a makefile should use @code{$(MKDIR_P) --
$(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
Finally, @code{AS_MKDIR_P} does not check for race condition
vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
@samp{@@MKDIR_P@@} is special, as its value may vary for different
configuration files.
The result of the test can be overridden by setting the variable
@code{MKDIR_P} or the cache variable @code{ac_cv_path_mkdir}.
@end defmac
@anchor{AC_PROG_LEX}
@defmac AC_PROG_LEX
@acindex{PROG_LEX}
@ovindex LEX
@ovindex LEXLIB
@cvindex YYTEXT_POINTER
@ovindex LEX_OUTPUT_ROOT
@caindex prog_LEX
If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
@option{-ll}, if found. If neither variant is available, set @code{LEX}
to @samp{:}; for packages that ship the generated @file{file.yy.c}
alongside the source @file{file.l}, this default allows users without a
lexer generator to still build the package even if the timestamp for
@file{file.l} is inadvertently changed.
Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
of to @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.
You are encouraged to use Flex in your sources, since it is both more
pleasant to use than plain Lex and the C source it produces is portable.
In order to ensure portability, however, you must either provide a
function @code{yywrap} or, if you don't use it (e.g., your scanner has
no @samp{#include}-like feature), simply include a @samp{%noyywrap}
statement in the scanner's source. Once this done, the scanner is
portable (unless @emph{you} felt free to use nonportable constructs) and
does not depend on any library. In this case, and in this case only, it
is suggested that you use this Autoconf snippet:
@example
AC_PROG_LEX
if test "x$LEX" != xflex; then
LEX="$SHELL $missing_dir/missing flex"
AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
AC_SUBST([LEXLIB], [''])
fi
@end example
The shell script @command{missing} can be found in the Automake
distribution.
Remember that the user may have supplied an alternate location in
@env{LEX}, so if Flex is required, it is better to check that the user
provided something sufficient by parsing the output of @samp{$LEX
--version} than by simply relying on @code{test "x$LEX" = xflex}.
To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
(indirectly) this macro twice, which causes an annoying but benign
``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
of Automake will fix this issue; meanwhile, just ignore this message.
As part of running the test, this macro may delete any file in the
configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
The result of this test can be influenced by setting the variable
@code{LEX} or the cache variable @code{ac_cv_prog_LEX}.
@end defmac
@anchor{AC_PROG_LN_S}
@defmac AC_PROG_LN_S
@acindex{PROG_LN_S}
@ovindex LN_S
If @samp{ln -s} works on the current file system (the operating system
and file system support symbolic links), set the output variable
@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
@code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -pR}.
If you make a link in a directory other than the current directory, its
meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
create links using @samp{$(LN_S)}, either find out which form is used
and adjust the arguments, or always invoke @code{ln} in the directory
where the link is to be created.
In other words, it does not work to do:
@example
$(LN_S) foo /x/bar
@end example
Instead, do:
@example
(cd /x && $(LN_S) foo bar)
@end example
@end defmac
@defmac AC_PROG_RANLIB
@acindex{PROG_RANLIB}
@ovindex RANLIB
@c @caindex prog_RANLIB
@c @caindex prog_ac_ct_RANLIB
Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
is found, and otherwise to @samp{:} (do nothing).
@end defmac
@defmac AC_PROG_SED
@acindex{PROG_SED}
@ovindex SED
@caindex path_SED
Set output variable @code{SED} to a Sed implementation that conforms to
Posix and does not have arbitrary length limits. Report an error if no
acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more
information about portability problems with Sed.
The result of this test can be overridden by setting the @code{SED} variable
and is cached in the @code{ac_cv_path_SED} variable.
@end defmac
@defmac AC_PROG_YACC
@acindex{PROG_YACC}
@evindex YACC
@evindex YFLAGS
@ovindex YACC
@caindex prog_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}.
The result of this test can be influenced by setting the variable
@code{YACC} or the cache variable @code{ac_cv_prog_YACC}.
@end defmac
@node Generic Programs
@subsection Generic Program and File Checks
These macros are used to find programs not covered by the ``particular''
test macros. If you need to check the behavior of a program as well as
find out whether it is present, you have to write your own test for it
(@pxref{Writing Tests}). By default, these macros use the environment
variable @env{PATH}. If you need to check for a program that might not
be in the user's @env{PATH}, you can pass a modified path to use
instead, like this:
@example
AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
[$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl
[/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc])
@end example
You are strongly encouraged to declare the @var{variable} passed to
@code{AC_CHECK_PROG} etc.@: as precious. @xref{Setting Output Variables},
@code{AC_ARG_VAR}, for more details.
@anchor{AC_CHECK_PROG}
@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @
@var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @
@ovar{reject})
@acindex{CHECK_PROG}
@caindex prog_@var{variable}
Check whether program @var{prog-to-check-for} exists in @var{path}. If
it is found, set @var{variable} to @var{value-if-found}, otherwise to
@var{value-if-not-found}, if given. Always pass over @var{reject} (an
absolute file name) even if it is the first found in the search path; in
that case, set @var{variable} using the absolute file name of the
@var{prog-to-check-for} found that is not @var{reject}. If
@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
@var{variable}. The result of this test can be overridden by setting the
@var{variable} variable or the cache variable
@code{ac_cv_prog_@var{variable}}.
@end defmac
@anchor{AC_CHECK_PROGS}
@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{CHECK_PROGS}
@caindex prog_@var{variable}
Check for each program in the blank-separated list
@var{progs-to-check-for} existing in the @var{path}. If one 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}. The result of
this test can be overridden by setting the @var{variable} variable or the
cache variable @code{ac_cv_prog_@var{variable}}.
@end defmac
@defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{CHECK_TARGET_TOOL}
Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
with a prefix of the target type as determined by
@code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
If the tool cannot be found with a prefix, and if the build and target
types are equal, then it is also searched for without a prefix.
As noted in @ref{Specifying Target Triplets}, the
target is rarely specified, because most of the time it is the same
as the host: it is the type of system for which any compiler tool in
the package produces code. What this macro looks for is,
for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
compiler driver @r{(@command{gcc} for the GNU C Compiler)}
uses to produce objects, archives or executables}.
@end defmac
@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{CHECK_TOOL}
@c @caindex prog_@var{VARIABLE}
@c @caindex prog_ac_ct_@var{VARIABLE}
Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
with a prefix of the host type as specified by @option{--host}, followed by a
dash. For example, if the user runs
@samp{configure --build=x86_64-gnu --host=i386-gnu}, then this call:
@example
AC_CHECK_TOOL([RANLIB], [ranlib], [:])
@end example
@noindent
sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
@var{path}, or otherwise to @samp{ranlib} if that program exists in
@var{path}, or to @samp{:} if neither program exists.
When cross-compiling, this macro will issue a warning if no program
prefixed with the host type could be found.
For more information, see @ref{Specifying Target Triplets}.
@end defmac
@defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{CHECK_TARGET_TOOLS}
Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
@var{progs-to-check-for} are checked with a prefix of the target type as
determined by @code{AC_CANONICAL_TARGET}, followed by a dash
(@pxref{Canonicalizing}). If none of the tools can be found with a
prefix, and if the build and target types are equal, then the first one
without a prefix is used. If a tool is found, set @var{variable} to
the name of that program. If none of the tools 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_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{CHECK_TOOLS}
Like @code{AC_CHECK_TOOL}, each of the tools in the list
@var{progs-to-check-for} are checked with a prefix of the host type as
determined by @code{AC_CANONICAL_HOST}, followed by a dash
(@pxref{Canonicalizing}). If none of the tools can be found with a
prefix, then the first one without a prefix is used. If a tool is found,
set @var{variable} to the name of that program. If none of the tools 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}.
When cross-compiling, this macro will issue a warning if no program
prefixed with the host type could be found.
For more information, see @ref{Specifying Target Triplets}.
@end defmac
@anchor{AC_PATH_PROG}
@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{PATH_PROG}
@caindex path_@var{variable}
Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
name of @var{prog-to-check-for} if found. The result of this test
can be overridden by setting the @var{variable} variable. A positive
result of this test is cached in the @code{ac_cv_path_@var{variable}}
variable.
@end defmac
@anchor{AC_PATH_PROGS}
@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{PATH_PROGS}
@caindex path_@var{variable}
Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
are found, set @var{variable} to the absolute name of the program
found. The result of this test can be overridden by setting the
@var{variable} variable. A positive result of this test is cached in
the @code{ac_cv_path_@var{variable}} variable.
@end defmac
@defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @
@var{progs-to-check-for}, @var{feature-test}, @
@ovar{action-if-not-found}, @dvar{path, $PATH})
@acindex{PATH_PROGS_FEATURE_CHECK}
@caindex path_@var{variable}
@vrindex ac_path_@var{variable}
@vrindex ac_path_@var{variable}_found
This macro was introduced in Autoconf 2.62. If @var{variable} is not
empty, then set the cache variable @code{ac_cv_path_@var{variable}} to
its value. Otherwise, check for each program in the blank-separated
list @var{progs-to-check-for} existing in @var{path}. For each program
found, execute @var{feature-test} with @code{ac_path_@var{variable}}
set to the absolute name of the candidate program. If no invocation of
@var{feature-test} sets the shell variable
@code{ac_cv_path_@var{variable}}, then @var{action-if-not-found} is
executed. @var{feature-test} will be run even when
@code{ac_cv_path_@var{variable}} is set, to provide the ability to
choose a better candidate found later in @var{path}; to accept the
current setting and bypass all further checks, @var{feature-test} can
execute @code{ac_path_@var{variable}_found=:}.
Note that this macro has some subtle differences from
@code{AC_CHECK_PROGS}. It is designed to be run inside
@code{AC_CACHE_VAL}, therefore, it should have no side effects. In
particular, @var{variable} is not set to the final value of
@code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically
run. Also, on failure, any action can be performed, whereas
@code{AC_CHECK_PROGS} only performs
@code{@var{variable}=@var{value-if-not-found}}.
Here is an example, similar to what Autoconf uses in its own configure
script. It will search for an implementation of @command{m4} that
supports the @code{indir} builtin, even if it goes by the name
@command{gm4} or is not the first implementation on @env{PATH}.
@example
AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4],
[AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4],
[[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4`
test "x$m4out" = x0 \
&& ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]],
[AC_MSG_ERROR([could not find m4 that supports indir])])])
AC_SUBST([M4], [$ac_cv_path_M4])
@end example
@end defmac
@defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{PATH_TARGET_TOOL}
Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
name of the program if it is found.
@end defmac
@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @
@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{PATH_TOOL}
Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
name of the program if it is found.
When cross-compiling, this macro will issue a warning if no program
prefixed with the host type could be found.
For more information, see @ref{Specifying Target Triplets}.
@end defmac
@node Files
@section Files
@cindex File, checking
You might also need to check for the existence of files. Before using
these macros, ask yourself whether a runtime test might not be a better
solution. Be aware that, like most Autoconf macros, they test a feature
of the host machine, and therefore, they die when cross-compiling.
@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @
@ovar{action-if-not-found})
@acindex{CHECK_FILE}
@caindex file_@var{file}
Check whether file @var{file} exists on the native system. If it is
found, execute @var{action-if-found}, otherwise do
@var{action-if-not-found}, if given. The result of this test is cached
in the @code{ac_cv_file_@var{file}} variable, with characters not
suitable for a variable name mapped to underscores.
@end defmac
@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @
@ovar{action-if-not-found})
@acindex{CHECK_FILES}
@caindex file_@var{file}
Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
for each file found. The results of each test are cached in the
@code{ac_cv_file_@var{file}} variable, with characters not suitable for
a variable name mapped to underscores.
@end defmac
@node Libraries
@section Library Files
@cindex Library, checking
The following macros check for the presence of certain C, C++, Fortran,
or Go library archive files.
@anchor{AC_CHECK_LIB}
@defmac AC_CHECK_LIB (@var{library}, @var{function}, @
@ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
@acindex{CHECK_LIB}
@caindex lib_@var{library}_@var{function}
Test whether the library @var{library} is available by trying to link
a test program that calls function @var{function} with the library.
@var{function} should be a function provided by the library.
Use the base
name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
the @var{library} argument.
@var{action-if-found} is a list of shell commands to run if the link
with the library succeeds; @var{action-if-not-found} is a list of shell
commands to run if the link fails. If @var{action-if-found} is not
specified, the default action prepends @option{-l@var{library}} to
@code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
capitals). This macro is intended to support building @code{LIBS} in
a right-to-left (least-dependent to most-dependent) fashion such that
library dependencies are satisfied as a natural side effect of
consecutive tests. Linkers are sensitive to library ordering
so the order in which @code{LIBS} is generated is important to reliable
detection of libraries.
If linking with @var{library} results in unresolved symbols that would
be resolved by linking with additional libraries, give those libraries
as the @var{other-libraries} argument, separated by spaces:
e.g., @option{-lXt -lX11}. Otherwise, this macro may fail to detect
that @var{library} is present, because linking the test program can
fail with unresolved symbols. The @var{other-libraries} argument
should be limited to cases where it is desirable to test for one library
in the presence of another that is not already in @code{LIBS}.
@code{AC_CHECK_LIB} requires some care in usage, and should be avoided
in some common cases. Many standard functions like @code{gethostbyname}
appear in the standard C library on some hosts, and in special libraries
like @code{nsl} on other hosts. On some hosts the special libraries
contain variant implementations that you may not want to use. These
days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
[nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
The result of this test is cached in the
@code{ac_cv_lib_@var{library}_@var{function}} variable.
@end defmac
@anchor{AC_SEARCH_LIBS}
@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @
@ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
@acindex{SEARCH_LIBS}
@caindex search_@var{function}
Search for a library defining @var{function} if it's not already
available. This equates to calling
@samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
no libraries, then for each library listed in @var{search-libs}.
Prepend @option{-l@var{library}} to @code{LIBS} for the first library found
to contain @var{function}, and run @var{action-if-found}. If the
function is not found, run @var{action-if-not-found}.
If linking with @var{library} results in unresolved symbols that would
be resolved by linking with additional libraries, give those libraries
as the @var{other-libraries} argument, separated by spaces:
e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
that @var{function} is present, because linking the test program
always fails with unresolved symbols.
The result of this test is cached in the
@code{ac_cv_search_@var{function}} variable as @samp{none required} if
@var{function} is already available, as @samp{no} if no library
containing @var{function} was found, otherwise as the
@option{-l@var{library}} option that needs to be prepended to @code{LIBS}.
@end defmac
@node Library Functions
@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
* Function Portability:: Pitfalls with usual functions
* Particular Functions:: Special handling to find certain functions
* Generic Functions:: How to find other functions
@end menu
@node Function Portability
@subsection Portability of C Functions
@cindex Portability of C functions
@cindex C function portability
Most usual functions can either be missing, or be buggy, or be limited
on some architectures. This section tries to make an inventory of these
portability issues. By definition, this list always requires
additions. A much more complete list is maintained by the Gnulib
project (@pxref{Gnulib}), covering @ref{Function Substitutes, ,
Current Posix Functions, gnulib, GNU gnulib}, @ref{Legacy Function
Substitutes, , Legacy Functions, gnulib, GNU gnulib}, and @ref{Glibc
Function Substitutes, , Glibc Functions, gnulib, GNU gnulib}. Please
help us keep the gnulib list as complete as possible.
@table @asis
@item @code{exit}
@c @fuindex exit
@prindex @code{exit}
On ancient hosts, @code{exit} returned @code{int}.
This is because @code{exit} predates @code{void}, and there was a long
tradition of it returning @code{int}.
On current hosts, the problem more likely is that @code{exit} is not
declared, due to C++ problems of some sort or another. For this reason
we suggest that test programs not invoke @code{exit}, but return from
@code{main} instead.
@item @code{free}
@c @fuindex free
@prindex @code{free}
The C standard says a call @code{free (NULL)} does nothing, but
some old systems don't support this (e.g., NextStep).
@item @code{isinf}
@itemx @code{isnan}
@c @fuindex isinf
@c @fuindex isnan
@prindex @code{isinf}
@prindex @code{isnan}
The C99 standard says that @code{isinf} and @code{isnan} are
macros. On some systems just macros are available
(e.g., HP-UX and Solaris 10), on
some systems both macros and functions (e.g., glibc 2.3.2), and on some
systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
these functions are declared in nonstandard headers like
@code{<sunmath.h>} and defined in non-default libraries like
@option{-lm} or @option{-lsunmath}.
The C99 @code{isinf} and @code{isnan} macros work correctly with
@code{long double} arguments, but pre-C99 systems that use functions
typically assume @code{double} arguments. On such a system,
@code{isinf} incorrectly returns true for a finite @code{long double}
argument that is outside the range of @code{double}.
The best workaround for these issues is to use gnulib modules
@code{isinf} and @code{isnan} (@pxref{Gnulib}). But a lighter weight
solution involves code like the following.
@smallexample
#include <math.h>
#ifndef isnan
# define isnan(x) \
(sizeof (x) == sizeof (long double) ? isnan_ld (x) \
: sizeof (x) == sizeof (double) ? isnan_d (x) \
: isnan_f (x))
static inline int isnan_f (float x) @{ return x != x; @}
static inline int isnan_d (double x) @{ return x != x; @}
static inline int isnan_ld (long double x) @{ return x != x; @}
#endif
#ifndef isinf
# define isinf(x) \
(sizeof (x) == sizeof (long double) ? isinf_ld (x) \
: sizeof (x) == sizeof (double) ? isinf_d (x) \
: isinf_f (x))
static inline int isinf_f (float x)
@{ return !isnan (x) && isnan (x - x); @}
static inline int isinf_d (double x)
@{ return !isnan (x) && isnan (x - x); @}
static inline int isinf_ld (long double x)
@{ return !isnan (x) && isnan (x - x); @}
#endif
@end smallexample
Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
compilers that lack the @code{inline} keyword. Some optimizing
compilers mishandle these definitions, but systems with that bug
typically have many other floating point corner-case compliance problems
anyway, so it's probably not worth worrying about.
@item @code{malloc}
@c @fuindex malloc
@prindex @code{malloc}
The C standard says a call @code{malloc (0)} is implementation
dependent. It can return either @code{NULL} or a new non-null pointer.
The latter is more common (e.g., the GNU C Library) but is by
no means universal. @code{AC_FUNC_MALLOC}
can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
@item @code{putenv}
@c @fuindex putenv
@prindex @code{putenv}
Posix prefers @code{setenv} to @code{putenv}; among other things,
@code{putenv} is not required of all Posix implementations, but
@code{setenv} is.
Posix specifies that @code{putenv} puts the given string directly in
@code{environ}, but some systems make a copy of it instead (e.g.,
glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might
not free it, causing a memory leak (e.g., FreeBSD 4).
On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
environment, but this is not standard usage and it dumps core
on some systems (e.g., AIX).
On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
environment, rather than inserting it with an empty value.
@item @code{realloc}
@c @fuindex realloc
@prindex @code{realloc}
The C standard says a call @code{realloc (NULL, size)} is equivalent
to @code{malloc (size)}, but some old systems don't support this (e.g.,
NextStep).
@item @code{signal} handler
@c @fuindex signal
@prindex @code{signal}
@prindex @code{sigaction}
Normally @code{signal} takes a handler function with a return type of
@code{void}, but some old systems required @code{int} instead. Any
actual @code{int} value returned is not used; this is only a
difference in the function prototype demanded.
All systems we know of in current use return @code{void}. The
@code{int} was to support K&R C, where of course @code{void} is not
available. The obsolete macro @code{AC_TYPE_SIGNAL}
(@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in
all cases.
In most cases, it is more robust to use @code{sigaction} when it is
available, rather than @code{signal}.
@item @code{snprintf}
@c @fuindex snprintf
@prindex @code{snprintf}
@c @fuindex vsnprintf
@prindex @code{vsnprintf}
The C99 standard says that if the output array isn't big enough
and if no other errors occur, @code{snprintf} and @code{vsnprintf}
truncate the output and return the number of bytes that ought to have
been produced. Some older systems return the truncated length (e.g.,
GNU C Library 2.0.x or IRIX 6.5), some a negative value
(e.g., earlier GNU C Library versions), and some the buffer
length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
older systems ignore the length and overrun the buffer (e.g., 64-bit
Solaris 7).
@item @code{sprintf}
@c @fuindex sprintf
@prindex @code{sprintf}
@c @fuindex vsprintf
@prindex @code{vsprintf}
The C standard says @code{sprintf} and @code{vsprintf} return the
number of bytes written. On some ancient systems (SunOS 4 for
instance) they return the buffer pointer instead, but these no
longer need to be worried about.
@item @code{sscanf}
@c @fuindex sscanf
@prindex @code{sscanf}
On various old systems, e.g., HP-UX 9, @code{sscanf} requires
that its
input string be writable (though it doesn't actually change it). This
can be a problem when using @command{gcc} since it normally puts
constant strings in read-only memory (@pxref{Incompatibilities,
Incompatibilities of GCC, , gcc, Using and
Porting the GNU Compiler Collection}). Apparently in some cases even
having format strings read-only can be a problem.
@item @code{strerror_r}
@c @fuindex strerror_r
@prindex @code{strerror_r}
Posix specifies that @code{strerror_r} returns an @code{int}, but many
systems (e.g., GNU C Library version 2.2.4) provide a
different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
can detect which is in use (@pxref{Particular Functions}).
@item @code{strnlen}
@c @fuindex strnlen
@prindex @code{strnlen}
AIX 4.3 provides a broken version which produces the
following results:
@example
strnlen ("foobar", 0) = 0
strnlen ("foobar", 1) = 3
strnlen ("foobar", 2) = 2
strnlen ("foobar", 3) = 1
strnlen ("foobar", 4) = 0
strnlen ("foobar", 5) = 6
strnlen ("foobar", 6) = 6
strnlen ("foobar", 7) = 6
strnlen ("foobar", 8) = 6
strnlen ("foobar", 9) = 6
@end example
@item @code{sysconf}
@c @fuindex sysconf
@prindex @code{sysconf}
@code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX
9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
@code{#ifdef}.
@item @code{unlink}
@c @fuindex unlink
@prindex @code{unlink}
The Posix spec says that @code{unlink} causes the given file to be
removed only after there are no more open file handles for it. Some
non-Posix hosts have trouble with this requirement, though,
and some DOS variants even corrupt the file system.
@item @code{unsetenv}
@c @fuindex unsetenv
@prindex @code{unsetenv}
On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
can be removed with a call @code{putenv ("FOO=")}, as described under
@code{putenv} above.
@item @code{va_copy}
@c @fuindex va_copy
@prindex @code{va_copy}
The C99 standard provides @code{va_copy} for copying
@code{va_list} variables. It may be available in older environments
too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
@code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
portability.
@item @code{va_list}
@c @fuindex va_list
@prindex @code{va_list}
@code{va_list} is not necessarily just a pointer. It can be a
@code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
not portable. Or it can be an array (e.g., @command{gcc} in some
PowerPC configurations), which means as a function parameter it can be
effectively call-by-reference and library routines might modify the
value back in the caller (e.g., @code{vsnprintf} in the GNU C Library
2.1).
@item Signed @code{>>}
Normally the C @code{>>} right shift of a signed type replicates the
high bit, giving a so-called ``arithmetic'' shift. But care should be
taken since Standard C doesn't require that behavior. On those
few processors without a native arithmetic shift (for instance Cray
vector systems) zero bits may be shifted in, the same as a shift of an
unsigned type.
@item Integer @code{/}
C divides signed integers by truncating their quotient toward zero,
yielding the same result as Fortran. However, before C99 the standard
allowed C implementations to take the floor or ceiling of the quotient
in some cases. Hardly any implementations took advantage of this
freedom, though, and it's probably not worth worrying about this issue
nowadays.
@end table
@node Particular Functions
@subsection Particular Function Checks
@cindex Function, checking
These macros check for particular C functions---whether they exist, and
in some cases how they respond when given certain arguments.
@anchor{AC_FUNC_ALLOCA}
@defmac AC_FUNC_ALLOCA
@acindex{FUNC_ALLOCA}
@cvindex C_ALLOCA
@cvindex HAVE_ALLOCA_H
@ovindex ALLOCA
@c @fuindex alloca
@prindex @code{alloca}
@hdrindex{alloca.h}
@c @caindex working_alloca_h
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{$@{LIBOBJDIR@}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}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs 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.
@example
@group
#ifdef STDC_HEADERS
# include <stdlib.h>
# include <stddef.h>
#else
# ifdef HAVE_STDLIB_H
# include <stdlib.h>
# endif
#endif
#ifdef HAVE_ALLOCA_H
# include <alloca.h>
#elif !defined alloca
# ifdef __GNUC__
# define alloca __builtin_alloca
# elif defined _AIX
# define alloca __alloca
# elif defined _MSC_VER
# include <malloc.h>
# define alloca _alloca
# elif !defined HAVE_ALLOCA
# ifdef __cplusplus
extern "C"
# endif
void *alloca (size_t);
# endif
#endif
@end group
@end example
@end defmac
@defmac AC_FUNC_CHOWN
@acindex{FUNC_CHOWN}
@cvindex HAVE_CHOWN
@c @fuindex chown
@prindex @code{chown}
@caindex func_chown_works
If the @code{chown} function is available and works (in particular, it
should accept @option{-1} for @code{uid} and @code{gid}), define
@code{HAVE_CHOWN}. The result of this macro is cached in the
@code{ac_cv_func_chown_works} variable.
@end defmac
@anchor{AC_FUNC_CLOSEDIR_VOID}
@defmac AC_FUNC_CLOSEDIR_VOID
@acindex{FUNC_CLOSEDIR_VOID}
@cvindex CLOSEDIR_VOID
@c @fuindex closedir
@prindex @code{closedir}
@caindex func_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.
Currently this test is implemented by running a test program. When
cross compiling the pessimistic assumption that @code{closedir} does not
return a meaningful value is made.
The result of this macro is cached in the @code{ac_cv_func_closedir_void}
variable.
This macro is obsolescent, as @code{closedir} returns a meaningful value
on current systems. New programs need not use this macro.
@end defmac
@defmac AC_FUNC_ERROR_AT_LINE
@acindex{FUNC_ERROR_AT_LINE}
@c @fuindex error_at_line
@prindex @code{error_at_line}
@caindex lib_error_at_line
If the @code{error_at_line} function is not found, require an
@code{AC_LIBOBJ} replacement of @samp{error}.
The result of this macro is cached in the @code{ac_cv_lib_error_at_line}
variable.
The @code{AC_FUNC_ERROR_AT_LINE} macro is obsolescent. New programs
should use Gnulib's @code{error} module. @xref{Gnulib}.
@end defmac
@defmac AC_FUNC_FNMATCH
@acindex{FUNC_FNMATCH}
@c @fuindex fnmatch
@prindex @code{fnmatch}
@caindex func_fnmatch_works
If the @code{fnmatch} function conforms to Posix, define
@code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
the bugs in Solaris 2.4.
Unlike the other specific
@code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
broken/missing @code{fnmatch}. This is for historical reasons.
See @code{AC_REPLACE_FNMATCH} below.
The result of this macro is cached in the @code{ac_cv_func_fnmatch_works}
variable.
This macro is obsolescent. New programs should use Gnulib's
@code{fnmatch-posix} module. @xref{Gnulib}.
@end defmac
@defmac AC_FUNC_FNMATCH_GNU
@acindex{FUNC_FNMATCH_GNU}
@c @fuindex fnmatch
@prindex @code{fnmatch}
@caindex func_fnmatch_gnu
Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
whether @code{fnmatch} supports GNU extensions. Detect common
implementation bugs, for example, the bugs in the GNU C
Library 2.1.
The result of this macro is cached in the @code{ac_cv_func_fnmatch_gnu}
variable.
This macro is obsolescent. New programs should use Gnulib's
@code{fnmatch-gnu} module. @xref{Gnulib}.
@end defmac
@anchor{AC_FUNC_FORK}
@defmac AC_FUNC_FORK
@acindex{FUNC_FORK}
@cvindex HAVE_VFORK_H
@cvindex HAVE_WORKING_FORK
@cvindex HAVE_WORKING_VFORK
@cvindex vfork
@c @fuindex fork
@prindex @code{fork}
@c @fuindex vfork
@prindex @code{vfork}
@hdrindex{vfork.h}
@c @caindex func_fork
@c @caindex func_fork_works
This macro checks for the @code{fork} and @code{vfork} functions. If a
working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
checks whether @code{fork} is just a stub by trying to run it.
If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
define @code{vfork} to be @code{fork} for backward compatibility with
previous versions of @command{autoconf}. 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. It is not considered
to be an implementation error if a child's invocation of @code{signal}
modifies the parent's signal handler, since child processes rarely change
their signal handlers.
Since this macro defines @code{vfork} only for backward compatibility with
previous versions of @command{autoconf} you're encouraged to define it
yourself in new code:
@example
@group
#ifndef HAVE_WORKING_VFORK
# define vfork fork
#endif
@end group
@end example
The results of this macro are cached in the @code{ac_cv_func_fork_works}
and @code{ac_cv_func_vfork_works} variables. In order to override the
test, you also need to set the @code{ac_cv_func_fork} and
@code{ac_cv_func_vfork} variables.
@end defmac
@defmac AC_FUNC_FSEEKO
@acindex{FUNC_FSEEKO}
@cvindex _LARGEFILE_SOURCE
@cvindex HAVE_FSEEKO
@c @fuindex fseeko
@prindex @code{fseeko}
@c @fuindex ftello
@prindex @code{ftello}
@c @caindex sys_largefile_source
If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
may occur when compiling with @code{AC_SYS_LARGEFILE} on
largefile-sensitive systems where @code{off_t} does not default to a
64bit entity. All systems with @code{fseeko} also supply @code{ftello}.
@end defmac
@defmac AC_FUNC_GETGROUPS
@acindex{FUNC_GETGROUPS}
@cvindex HAVE_GETGROUPS
@ovindex GETGROUPS_LIBS
@c @fuindex getgroups
@prindex @code{getgroups}
@caindex func_getgroups_works
If the @code{getgroups} function is available and works (unlike on
Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
@end defmac
@anchor{AC_FUNC_GETLOADAVG}
@defmac AC_FUNC_GETLOADAVG
@acindex{FUNC_GETLOADAVG}
@cvindex SVR4
@cvindex DGUX
@cvindex UMAX
@cvindex UMAX4_3
@cvindex HAVE_NLIST_H
@cvindex NLIST_NAME_UNION
@cvindex GETLOADAVG_PRIVILEGED
@cvindex NEED_SETGID
@cvindex C_GETLOADAVG
@ovindex LIBOBJS
@ovindex NEED_SETGID
@ovindex KMEM_GROUP
@ovindex GETLOADAVG_LIBS
@c @fuindex getloadavg
@prindex @code{getloadavg}
Check how to get the system load averages. To perform its tests
properly, this macro needs the file @file{getloadavg.c}; therefore, be
sure to set the @code{AC_LIBOBJ} replacement directory properly (see
@ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
If the system has the @code{getloadavg} function, define
@code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
@code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
@samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
possibly define several other C preprocessor macros and output
variables:
@enumerate
@item
Define @code{C_GETLOADAVG}.
@item
Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
those systems.
@item
@hdrindex{nlist.h}
If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
@item
If @samp{struct nlist} has an @samp{n_un.n_name} member, define
@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
@code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
@item
Programs may need to be installed set-group-ID (or set-user-ID) for
@code{getloadavg} to work. In this case, define
@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
to @samp{true} (and otherwise to @samp{false}), and set
@code{KMEM_GROUP} to the name of the group that should own the installed
program.
@end enumerate
The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
@end defmac
@anchor{AC_FUNC_GETMNTENT}
@defmac AC_FUNC_GETMNTENT
@acindex{FUNC_GETMNTENT}
@cvindex HAVE_GETMNTENT
@c @fuindex getmntent
@prindex @code{getmntent}
@caindex search_getmntent
Check for @code{getmntent} in the standard C library, and then in the
@file{sun}, @file{seq}, and @file{gen} libraries, for UNICOS,
IRIX 4, PTX, and UnixWare, respectively. Then, if
@code{getmntent} is available, define @code{HAVE_GETMNTENT} and set
@code{ac_cv_func_getmntent} to @code{yes}. Otherwise set
@code{ac_cv_func_getmntent} to @code{no}.
The result of this macro can be overridden by setting the cache variable
@code{ac_cv_search_getmntent}.
@end defmac
@defmac AC_FUNC_GETPGRP
@acindex{FUNC_GETPGRP}
@cvindex GETPGRP_VOID
@c @fuindex getpgid
@c @fuindex getpgrp
@prindex @code{getpgid}
@prindex @code{getpgrp}
@caindex func_getpgrp_void
Define @code{GETPGRP_VOID} if it is an error to pass 0 to
@code{getpgrp}; this is the Posix behavior. On older BSD
systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
behaves like Posix's @code{getpgid}.
@example
#ifdef GETPGRP_VOID
pid = getpgrp ();
#else
pid = getpgrp (0);
#endif
@end example
This macro does not check whether
@code{getpgrp} exists at all; if you need to work in that situation,
first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
The result of this macro is cached in the @code{ac_cv_func_getpgrp_void}
variable.
This macro is obsolescent, as current systems have a @code{getpgrp}
whose signature conforms to Posix. New programs need not use this macro.
@end defmac
@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
@acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
@c @fuindex lstat
@prindex @code{lstat}
@caindex func_lstat_dereferences_slashed_symlink
If @file{link} is a symbolic link, then @code{lstat} should treat
@file{link/} the same as @file{link/.}. However, many older
@code{lstat} implementations incorrectly ignore trailing slashes.
It is safe to assume that if @code{lstat} incorrectly ignores
trailing slashes, then other symbolic-link-aware functions like
@code{unlink} also incorrectly ignore trailing slashes.
If @code{lstat} behaves properly, define
@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
@code{AC_LIBOBJ} replacement of @code{lstat}.
The result of this macro is cached in the
@code{ac_cv_func_lstat_dereferences_slashed_symlink} variable.
The @code{AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} macro is obsolescent.
New programs should use Gnulib's @code{lstat} module. @xref{Gnulib}.
@end defmac
@defmac AC_FUNC_MALLOC
@acindex{FUNC_MALLOC}
@cvindex HAVE_MALLOC
@cvindex malloc
@c @fuindex malloc
@prindex @code{malloc}
@caindex func_malloc_0_nonnull
If the @code{malloc} function is compatible with the GNU C
library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
@code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
@samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
native @code{malloc} is not used in the main project.
Typically, the replacement file @file{malloc.c} should look like (note
the @samp{#undef malloc}):
@verbatim
#include <config.h>
#undef malloc
#include <sys/types.h>
void *malloc ();
/* Allocate an N-byte block of memory from the heap.
If N is zero, allocate a 1-byte block. */
void *
rpl_malloc (size_t n)
{
if (n == 0)
n = 1;
return malloc (n);
}
@end verbatim
The result of this macro is cached in the
@code{ac_cv_func_malloc_0_nonnull} variable.
@end defmac
@defmac AC_FUNC_MBRTOWC
@acindex{FUNC_MBRTOWC}
@cvindex HAVE_MBRTOWC
@c @fuindex mbrtowc
@prindex @code{mbrtowc}
@caindex func_mbrtowc
Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
type @code{mbstate_t} are properly declared.
The result of this macro is cached in the @code{ac_cv_func_mbrtowc}
variable.
@end defmac
@defmac AC_FUNC_MEMCMP
@acindex{FUNC_MEMCMP}
@ovindex LIBOBJS
@c @fuindex memcmp
@prindex @code{memcmp}
@caindex func_memcmp_working
If the @code{memcmp} function is not available, or does not work on
8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
bytes or more and with at least one buffer not starting on a 4-byte
boundary (such as the one on NeXT x86 OpenStep), require an
@code{AC_LIBOBJ} replacement for @samp{memcmp}.
The result of this macro is cached in the
@code{ac_cv_func_memcmp_working} variable.
This macro is obsolescent, as current systems have a working
@code{memcmp}. New programs need not use this macro.
@end defmac
@defmac AC_FUNC_MKTIME
@acindex{FUNC_MKTIME}
@ovindex LIBOBJS
@c @fuindex mktime
@prindex @code{mktime}
@caindex func_working_mktime
If the @code{mktime} function is not available, or does not work
correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
For the purposes of this test, @code{mktime} should conform to the
Posix standard and should be the inverse of
@code{localtime}.
The result of this macro is cached in the
@code{ac_cv_func_working_mktime} variable.
The @code{AC_FUNC_MKTIME} macro is obsolescent. New programs should
use Gnulib's @code{mktime} module. @xref{Gnulib}.
@end defmac
@anchor{AC_FUNC_MMAP}
@defmac AC_FUNC_MMAP
@acindex{FUNC_MMAP}
@cvindex HAVE_MMAP
@c @fuindex mmap
@prindex @code{mmap}
@caindex func_mmap_fixed_mapped
If the @code{mmap} function exists and works correctly, define
@code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
memory.
The result of this macro is cached in the
@code{ac_cv_func_mmap_fixed_mapped} variable.
@end defmac
@defmac AC_FUNC_OBSTACK
@acindex{FUNC_OBSTACK}
@cvindex HAVE_OBSTACK
@cindex obstack
@caindex func_obstack
If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
@code{AC_LIBOBJ} replacement for @samp{obstack}.
The result of this macro is cached in the @code{ac_cv_func_obstack}
variable.
@end defmac
@defmac AC_FUNC_REALLOC
@acindex{FUNC_REALLOC}
@cvindex HAVE_REALLOC
@cvindex realloc
@c @fuindex realloc
@prindex @code{realloc}
@caindex func_realloc_0_nonnull
If the @code{realloc} function is compatible with the GNU C
library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
@code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
@samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
the native @code{realloc} is not used in the main project. See
@code{AC_FUNC_MALLOC} for details.
The result of this macro is cached in the
@code{ac_cv_func_realloc_0_nonnull} variable.
@end defmac
@defmac AC_FUNC_SELECT_ARGTYPES
@acindex{FUNC_SELECT_ARGTYPES}
@cvindex SELECT_TYPE_ARG1
@cvindex SELECT_TYPE_ARG234
@cvindex SELECT_TYPE_ARG5
@c @fuindex select
@prindex @code{select}
@c @caindex func_select_args
Determines the correct type to be passed for each of the
@code{select} function's arguments, and defines those types
in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
This macro is obsolescent, as current systems have a @code{select} whose
signature conforms to Posix. New programs need not use this macro.
@end defmac
@defmac AC_FUNC_SETPGRP
@acindex{FUNC_SETPGRP}
@cvindex SETPGRP_VOID
@c @fuindex setpgrp
@prindex @code{setpgrp}
@caindex func_setpgrp_void
If @code{setpgrp} takes no argument (the Posix version), define
@code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes
two process IDs as arguments. This macro does not check whether
@code{setpgrp} exists at all; if you need to work in that situation,
first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
The result of this macro is cached in the @code{ac_cv_func_setpgrp_void}
variable.
This macro is obsolescent, as current systems have a @code{setpgrp}
whose signature conforms to Posix. New programs need not use this macro.
@end defmac
@defmac AC_FUNC_STAT
@defmacx AC_FUNC_LSTAT
@acindex{FUNC_STAT}
@acindex{FUNC_LSTAT}
@cvindex HAVE_STAT_EMPTY_STRING_BUG
@cvindex HAVE_LSTAT_EMPTY_STRING_BUG
@c @fuindex stat
@prindex @code{stat}
@c @fuindex lstat
@prindex @code{lstat}
@caindex func_stat_empty_string_bug
@caindex func_lstat_empty_string_bug
Determine whether @code{stat} or @code{lstat} have the bug that it
succeeds when given the zero-length file name as argument. The @code{stat}
and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
this.
If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
replacement of it.
The results of these macros are cached in the
@code{ac_cv_func_stat_empty_string_bug} and the
@code{ac_cv_func_lstat_empty_string_bug} variables, respectively.
These macros are obsolescent, as no current systems have the bug.
New programs need not use these macros.
@end defmac
@anchor{AC_FUNC_STRCOLL}
@defmac AC_FUNC_STRCOLL
@acindex{FUNC_STRCOLL}
@cvindex HAVE_STRCOLL
@c @fuindex strcoll
@prindex @code{strcoll}
@caindex func_strcoll_works
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} that should not be used.
The result of this macro is cached in the @code{ac_cv_func_strcoll_works}
variable.
@end defmac
@defmac AC_FUNC_STRERROR_R
@acindex{FUNC_STRERROR_R}
@cvindex HAVE_STRERROR_R
@cvindex HAVE_DECL_STRERROR_R
@cvindex STRERROR_R_CHAR_P
@c @fuindex strerror_r
@caindex func_strerror_r_char_p
@prindex @code{strerror_r}
If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
@code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
returns an @code{int} error number. The Thread-Safe Functions option of
Posix requires @code{strerror_r} to return @code{int}, but
many systems (including, for example, version 2.2.4 of the GNU C
Library) return a @code{char *} value that is not necessarily equal to
the buffer argument.
The result of this macro is cached in the
@code{ac_cv_func_strerror_r_char_p} variable.
@end defmac
@anchor{AC_FUNC_STRFTIME}
@defmac AC_FUNC_STRFTIME
@acindex{FUNC_STRFTIME}
@cvindex HAVE_STRFTIME
@c @fuindex strftime
@prindex @code{strftime}
Check for @code{strftime} in the @file{intl} library, for SCO Unix.
Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
This macro is obsolescent, as no current systems require the @file{intl}
library for @code{strftime}. New programs need not use this macro.
@end defmac
@defmac AC_FUNC_STRTOD
@acindex{FUNC_STRTOD}
@ovindex POW_LIB
@c @fuindex strtod
@prindex @code{strtod}
@caindex func_strtod
@caindex func_pow
If the @code{strtod} function does not exist or doesn't work correctly,
ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
because @file{strtod.c} is likely to need @samp{pow}, set the output
variable @code{POW_LIB} to the extra library needed.
This macro caches its result in the @code{ac_cv_func_strtod} variable
and depends upon the result in the @code{ac_cv_func_pow} variable.
The @code{AC_FUNC_STRTOD} macro is obsolescent. New programs should
use Gnulib's @code{strtod} module. @xref{Gnulib}.
@end defmac
@defmac AC_FUNC_STRTOLD
@acindex{FUNC_STRTOLD}
@cvindex HAVE_STRTOLD
@prindex @code{strtold}
@caindex func_strtold
If the @code{strtold} function exists and conforms to C99, define
@code{HAVE_STRTOLD}.
This macro caches its result in the @code{ac_cv_func_strtold} variable.
@end defmac
@defmac AC_FUNC_STRNLEN
@acindex{FUNC_STRNLEN}
@cvindex HAVE_STRNLEN
@c @fuindex strnlen
@prindex @code{strnlen}
@caindex func_strnlen_working
If the @code{strnlen} function is not available, or is buggy (like the one
from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it.
This macro caches its result in the @code{ac_cv_func_strnlen_working}
variable.
@end defmac
@anchor{AC_FUNC_UTIME_NULL}
@defmac AC_FUNC_UTIME_NULL
@acindex{FUNC_UTIME_NULL}
@cvindex HAVE_UTIME_NULL
@c @fuindex utime
@prindex @code{utime}
@caindex func_utime_null
If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
the present, define @code{HAVE_UTIME_NULL}.
This macro caches its result in the @code{ac_cv_func_utime_null}
variable.
This macro is obsolescent, as all current systems have a @code{utime}
that behaves this way. New programs need not use this macro.
@end defmac
@anchor{AC_FUNC_VPRINTF}
@defmac AC_FUNC_VPRINTF
@acindex{FUNC_VPRINTF}
@cvindex HAVE_VPRINTF
@cvindex HAVE_DOPRNT
@c @fuindex vprintf
@prindex @code{vprintf}
@c @fuindex vsprintf
@prindex @code{vsprintf}
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.)
This macro is obsolescent, as all current systems have @code{vprintf}.
New programs need not use this macro.
@end defmac
@defmac AC_REPLACE_FNMATCH
@acindex{REPLACE_FNMATCH}
@c @fuindex fnmatch
@prindex @code{fnmatch}
@hdrindex{fnmatch.h}
@caindex func_fnmatch_works
If the @code{fnmatch} function does not conform to Posix (see
@code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
copy of the source code of GNU @code{fnmatch}. If necessary,
this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
@file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
included in place of the system @code{<fnmatch.h>}.
This macro caches its result in the @code{ac_cv_func_fnmatch_works}
variable.
This macro is obsolescent, as it assumes the use of particular source
files. New programs should use Gnulib's @code{fnmatch-posix} module,
which provides this macro along with the source files. @xref{Gnulib}.
@end defmac
@node Generic Functions
@subsection Generic Function Checks
These macros are used to find functions not covered by the ``particular''
test macros. If the functions might be in libraries other than the
default C library, first call @code{AC_CHECK_LIB} for those libraries.
If you need to check the behavior of a function as well as find out
whether it is present, you have to write your own test for
it (@pxref{Writing Tests}).
@anchor{AC_CHECK_FUNC}
@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @
@ovar{action-if-not-found})
@acindex{CHECK_FUNC}
@caindex func_@var{function}
If C function @var{function} is available, run shell commands
@var{action-if-found}, otherwise @var{action-if-not-found}. 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(C++)} has been called, since C is more
standardized than C++. (@pxref{Language Choice}, for more information
about selecting the language for checks.)
This macro caches its result in the @code{ac_cv_func_@var{function}}
variable.
@end defmac
@anchor{AC_CHECK_FUNCS}
@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @
@ovar{action-if-not-found})
@acindex{CHECK_FUNCS}
@cvindex HAVE_@var{function}
For each @var{function} enumerated in the blank-or-newline-separated argument
list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
If @var{action-if-found} is given, it is additional shell code to
execute when one of the functions is found. You can give it a value of
@samp{break} to break out of the loop on the first match. If
@var{action-if-not-found} is given, it is executed when one of the
functions is not found.
Results are cached for each @var{function} as in @code{AC_CHECK_FUNC}.
@end defmac
@defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
@acindex{CHECK_FUNCS_ONCE}
@cvindex HAVE_@var{function}
For each @var{function} enumerated in the blank-or-newline-separated argument
list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
checking code at most once, so that @command{configure} is smaller and
faster; but the checks cannot be conditionalized and are always done once,
early during the @command{configure} run.
@end defmac
@sp 1
Autoconf follows a philosophy that was formed over the years by those
who have struggled for portability: isolate the portability issues in
specific files, and then program as if you were in a Posix
environment. Some functions may be missing or unfixable, and your
package must be ready to replace them.
Suitable replacements for many such problem functions are available from
Gnulib (@pxref{Gnulib}).
@defmac AC_LIBOBJ (@var{function})
@acindex{LIBOBJ}
@ovindex LIBOBJS
Specify that @samp{@var{function}.c} must be included in the executables
to replace a missing or broken implementation of @var{function}.
@vrindex ac_objext
Technically, it adds @samp{@var{function}.$ac_objext} to the output
variable @code{LIBOBJS} if it is not already in, and calls
@code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
directly change @code{LIBOBJS}, since this is not traceable.
@end defmac
@defmac AC_LIBSOURCE (@var{file})
@acindex{LIBSOURCE}
Specify that @var{file} might be needed to compile the project. If you
need to know what files might be needed by a @file{configure.ac}, you
should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
This macro is called automatically from @code{AC_LIBOBJ}, but you must
call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
that case, since shell variables cannot be traced statically, you must
pass to @code{AC_LIBSOURCE} any possible files that the shell variable
might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
@code{"foo"} or @code{"bar"}, you should do:
@example
AC_LIBSOURCE([foo.c])
AC_LIBSOURCE([bar.c])
AC_LIBOBJ([$foo_or_bar])
@end example
@noindent
There is usually a way to avoid this, however, and you are encouraged to
simply call @code{AC_LIBOBJ} with literal arguments.
Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
slightly different semantics: the old macro took the function name,
e.g., @code{foo}, as its argument rather than the file name.
@end defmac
@defmac AC_LIBSOURCES (@var{files})
@acindex{LIBSOURCES}
Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
comma-separated M4 list. Thus, the above example might be rewritten:
@example
AC_LIBSOURCES([foo.c, bar.c])
AC_LIBOBJ([$foo_or_bar])
@end example
@end defmac
@defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
@acindex{CONFIG_LIBOBJ_DIR}
Specify that @code{AC_LIBOBJ} replacement files are to be found in
@var{directory}, a name relative to the top level of the
source tree. The replacement directory defaults to @file{.}, the top
level directory, and the most typical value is @file{lib}, corresponding
to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
@command{configure} might need to know the replacement directory for the
following reasons: (i) some checks use the replacement files, (ii) some
macros bypass broken system headers by installing links to the
replacement headers (iii) when used in conjunction with Automake,
within each makefile, @var{directory} is used as a relative path
from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
@code{LTLIBOBJS}, etc.
@end defmac
@sp 1
It is common to merely check for the existence of a function, and ask
for its @code{AC_LIBOBJ} replacement if missing. The following macro is
a convenient shorthand.
@defmac AC_REPLACE_FUNCS (@var{function}@dots{})
@acindex{REPLACE_FUNCS}
@cvindex HAVE_@var{function}
@ovindex LIBOBJS
Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
@var{action-if-not-found}. You can declare your replacement function by
enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
system has the function, it probably declares it in a header file you
should be including, so you shouldn't redeclare it lest your declaration
conflict.
@end defmac
@node Header Files
@section Header Files
@cindex Header, checking
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
* Header Portability:: Collected knowledge on common headers
* Particular Headers:: Special handling to find certain headers
* Generic Headers:: How to find other headers
@end menu
@node Header Portability
@subsection Portability of Headers
@cindex Portability of headers
@cindex Header portability
This section documents some collected knowledge about common headers,
and the problems they cause. By definition, this list always requires
additions. A much more complete list is maintained by the Gnulib
project (@pxref{Gnulib}), covering @ref{Header File Substitutes, ,
Posix Headers, gnulib, GNU gnulib} and @ref{Glibc Header File
Substitutes, , Glibc Headers, gnulib, GNU gnulib}. Please help us keep
the gnulib list as complete as possible.
@table @asis
@item @file{limits.h}
C99 says that @file{limits.h} defines @code{LLONG_MIN},
@code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
environments (e.g., default GCC 4.0.2 + glibc 2.4) do not
define them.
@item @file{inttypes.h} vs.@: @file{stdint.h}
@hdrindex{inttypes.h}
@hdrindex{stdint.h}
The C99 standard says that @file{inttypes.h} includes
@file{stdint.h}, so there's no need to include @file{stdint.h}
separately in a standard environment. Some implementations have
@file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
know of any implementation that has @file{stdint.h} but not
@file{inttypes.h}.
@item @file{linux/irda.h}
@hdrindex{linux/irda.h}
It requires @file{linux/types.h} and @file{sys/socket.h}.
@item @file{linux/random.h}
@hdrindex{linux/random.h}
It requires @file{linux/types.h}.
@item @file{net/if.h}
@hdrindex{net/if.h}
On Darwin, this file requires that @file{sys/socket.h} be included
beforehand. One should run:
@example
AC_CHECK_HEADERS([sys/socket.h])
AC_CHECK_HEADERS([net/if.h], [], [],
[#include <stdio.h>
#ifdef STDC_HEADERS
# include <stdlib.h>
# include <stddef.h>
#else
# ifdef HAVE_STDLIB_H
# include <stdlib.h>
# endif
#endif
#ifdef HAVE_SYS_SOCKET_H
# include <sys/socket.h>
#endif
])
@end example
@item @file{netinet/if_ether.h}
@hdrindex{netinet/if_ether.h}
On Darwin, this file requires that @file{stdio.h} and
@file{sys/socket.h} be included beforehand. One should run:
@example
AC_CHECK_HEADERS([sys/socket.h])
AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
[#include <stdio.h>
#ifdef STDC_HEADERS
# include <stdlib.h>
# include <stddef.h>
#else
# ifdef HAVE_STDLIB_H
# include <stdlib.h>
# endif
#endif
#ifdef HAVE_SYS_SOCKET_H
# include <sys/socket.h>
#endif
])
@end example
@item @file{stdint.h}
See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
@item @file{stdlib.h}
@hdrindex{stdlib.h}
On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
@item @file{sys/mount.h}
@hdrindex{sys/mount.h}
On FreeBSD 4.8 on ia32 and using gcc version 2.95.4,
@file{sys/params.h} is a prerequisite.
@item @file{sys/ptem.h}
@hdrindex{sys/ptem.h}
On Solaris 8, @file{sys/stream.h} is a prerequisite.
@item @file{sys/socket.h}
@hdrindex{sys/socket.h}
On Darwin, @file{stdlib.h} is a prerequisite.
@item @file{sys/ucred.h}
@hdrindex{sys/ucred.h}
On Tru64 5.1, @file{sys/types.h} is a prerequisite.
@item @file{X11/extensions/scrnsaver.h}
@hdrindex{X11/extensions/scrnsaver.h}
Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
so required that you might not even consider looking for it.
@example
AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
[[#include <X11/Xlib.h>
]])
@end example
@end table
@node Particular Headers
@subsection Particular Header Checks
These macros check for particular system header files---whether they
exist, and in some cases whether they declare certain symbols.
@defmac AC_CHECK_HEADER_STDBOOL
@acindex{CHECK_HEADER_STDBOOL}
@cvindex HAVE__BOOL
@hdrindex{stdbool.h}
@caindex header_stdbool_h
Check whether @file{stdbool.h} exists and conforms to C99, and cache the
result in the @code{ac_cv_header_stdbool_h} variable. If the type
@code{_Bool} is defined, define @code{HAVE__BOOL} to 1.
This macro is intended for use by Gnulib (@pxref{Gnulib}) and other
packages that supply a substitute @file{stdbool.h} on platforms lacking
a conforming one. The @code{AC_HEADER_STDBOOL} macro is better for code
that explicitly checks for @file{stdbool.h}.
@end defmac
@defmac AC_HEADER_ASSERT
@acindex{HEADER_ASSERT}
@cvindex NDEBUG
@hdrindex{assert.h}
Check whether to enable assertions in the style of @file{assert.h}.
Assertions are enabled by default, but the user can override this by
invoking @command{configure} with the @option{--disable-assert} option.
@end defmac
@anchor{AC_HEADER_DIRENT}
@defmac AC_HEADER_DIRENT
@acindex{HEADER_DIRENT}
@cvindex HAVE_DIRENT_H
@cvindex HAVE_NDIR_H
@cvindex HAVE_SYS_DIR_H
@cvindex HAVE_SYS_NDIR_H
@hdrindex{dirent.h}
@hdrindex{sys/ndir.h}
@hdrindex{sys/dir.h}
@hdrindex{ndir.h}
Check for the following header files. For the first one that is
found and defines @samp{DIR}, define the listed C preprocessor macro:
@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
@item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
@item @file{ndir.h} @tab @code{HAVE_NDIR_H}
@end multitable
The directory-library declarations in your source code should look
something like the following:
@example
@group
#include <sys/types.h>
#ifdef HAVE_DIRENT_H
# include <dirent.h>
# define NAMLEN(dirent) strlen ((dirent)->d_name)
#else
# define dirent direct
# define NAMLEN(dirent) ((dirent)->d_namlen)
# ifdef HAVE_SYS_NDIR_H
# include <sys/ndir.h>
# endif
# ifdef HAVE_SYS_DIR_H
# include <sys/dir.h>
# endif
# ifdef HAVE_NDIR_H
# include <ndir.h>
# endif
#endif
@end group
@end example
Using the above declarations, the program would declare variables to be
of 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.
This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
This macro is obsolescent, as all current systems with directory
libraries have @code{<dirent.h>}. New programs need not use this macro.
Also see @code{AC_STRUCT_DIRENT_D_INO} and
@code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
@end defmac
@anchor{AC_HEADER_MAJOR}
@defmac AC_HEADER_MAJOR
@acindex{HEADER_MAJOR}
@cvindex MAJOR_IN_MKDEV
@cvindex MAJOR_IN_SYSMACROS
@hdrindex{sys/mkdev.h}
@hdrindex{sys/sysmacros.h}
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_RESOLV
@acindex{HEADER_RESOLV}
@cvindex HAVE_RESOLV_H
@hdrindex{resolv.h}
Checks for header @file{resolv.h}, checking for prerequisites first.
To properly use @file{resolv.h}, your code should contain something like
the following:
@verbatim
#ifdef HAVE_SYS_TYPES_H
# include <sys/types.h>
#endif
#ifdef HAVE_NETINET_IN_H
# include <netinet/in.h> /* inet_ functions / structs */
#endif
#ifdef HAVE_ARPA_NAMESER_H
# include <arpa/nameser.h> /* DNS HEADER struct */
#endif
#ifdef HAVE_NETDB_H
# include <netdb.h>
#endif
#include <resolv.h>
@end verbatim
@end defmac
@anchor{AC_HEADER_STAT}
@defmac AC_HEADER_STAT
@acindex{HEADER_STAT}
@cvindex STAT_MACROS_BROKEN
@hdrindex{sys/stat.h}
If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: 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.
This macro is obsolescent, as no current systems have the bug.
New programs need not use this macro.
@end defmac
@defmac AC_HEADER_STDBOOL
@acindex{HEADER_STDBOOL}
@cvindex HAVE_STDBOOL_H
@cvindex HAVE__BOOL
@hdrindex{stdbool.h}
@caindex header_stdbool_h
If @file{stdbool.h} exists and conforms to C99, define
@code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
@code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
program could contain the following code:
@example
@group
#ifdef HAVE_STDBOOL_H
# include <stdbool.h>
#else
# ifndef HAVE__BOOL
# ifdef __cplusplus
typedef bool _Bool;
# else
# define _Bool signed char
# endif
# endif
# define bool _Bool
# define false 0
# define true 1
# define __bool_true_false_are_defined 1
#endif
@end group
@end example
Alternatively you can use the @samp{stdbool} package of Gnulib
(@pxref{Gnulib}). It simplifies your code so that it can say just
@code{#include <stdbool.h>}, and it adds support for less-common
platforms.
This macro caches its result in the @code{ac_cv_header_stdbool_h}
variable.
This macro differs from @code{AC_CHECK_HEADER_STDBOOL} only in that it
defines @code{HAVE_STDBOOL_H} whereas @code{AC_CHECK_HEADER_STDBOOL}
does not.
@end defmac
@anchor{AC_HEADER_STDC}
@defmac AC_HEADER_STDC
@acindex{HEADER_STDC}
@cvindex STDC_HEADERS
@hdrindex{stdlib.h}
@hdrindex{stdarg.h}
@hdrindex{string.h}
@hdrindex{float.h}
@hdrindex{ctype.h}
@caindex header_stdc
Define @code{STDC_HEADERS} if the system has C header files
conforming to ANSI C89 (ISO C90).
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 C89 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 the C standard requires.
If you use this macro, your code can refer to @code{STDC_HEADERS} to
determine whether the system has conforming header files (and probably C
library functions).
This macro caches its result in the @code{ac_cv_header_stdc} variable.
This macro is obsolescent, as current systems have conforming header
files. New programs need not use this macro.
@hdrindex{string.h}
@hdrindex{strings.h}
Nowadays @file{string.h} is part of the C standard and declares functions like
@code{strcpy}, and @file{strings.h} is standardized by Posix and declares
BSD functions like @code{bcopy}; but
historically, string functions were a major sticking point in this area.
If you still want to worry about portability to ancient systems without
standard 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 ancient systems
contained a mix of functions from the C standard and from BSD;
some were mostly standard but lacked @samp{memmove}; some defined the
BSD functions as macros in @file{string.h} or
@file{strings.h}; some had only the BSD functions but
@file{string.h}; some declared 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 had the
standard versions of those then it probably had most of the others.
If you put the following in @file{configure.ac}:
@example
# This example is obsolescent.
# Nowadays you can omit these macro calls.
AC_HEADER_STDC
AC_CHECK_FUNCS([strchr memcpy])
@end example
@noindent
then, in your code, you can use declarations like this:
@example
@group
/* This example is obsolescent.
Nowadays you can just #include <string.h>. */
#ifdef 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))
# 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 don't
suffice to port to ancient hosts; 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])}.
@end defmac
@defmac AC_HEADER_SYS_WAIT
@acindex{HEADER_SYS_WAIT}
@cvindex HAVE_SYS_WAIT_H
@hdrindex{sys/wait.h}
@caindex header_sys_wait_h
If @file{sys/wait.h} exists and is compatible with Posix, define
@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
does not exist, or if it uses the old BSD @code{union wait} instead
of @code{int} to store a status value. If @file{sys/wait.h} is not
Posix compatible, then instead of including it, define the
Posix macros with their usual interpretations. Here is an
example:
@example
@group
#include <sys/types.h>
#ifdef HAVE_SYS_WAIT_H
# include <sys/wait.h>
#endif
#ifndef WEXITSTATUS
# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
#endif
#ifndef WIFEXITED
# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
#endif
@end group
@end example
@noindent
This macro caches its result in the @code{ac_cv_header_sys_wait_h}
variable.
This macro is obsolescent, as current systems are compatible with Posix.
New programs need not use this macro.
@end defmac
@cvindex _POSIX_VERSION
@hdrindex{unistd.h}
@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
Posix systems. If there is no @file{unistd.h}, it is definitely
not a Posix system. However, some non-Posix systems do
have @file{unistd.h}.
The way to check whether the system supports Posix is:
@example
@group
#ifdef HAVE_UNISTD_H
# include <sys/types.h>
# include <unistd.h>
#endif
#ifdef _POSIX_VERSION
/* Code for Posix systems. */
#endif
@end group
@end example
@anchor{AC_HEADER_TIME}
@defmac AC_HEADER_TIME
@acindex{HEADER_TIME}
@cvindex TIME_WITH_SYS_TIME
@hdrindex{time.h}
@hdrindex{sys/time.h}
@caindex header_time
If a program may include both @file{time.h} and @file{sys/time.h},
define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
@file{sys/time.h} included @file{time.h}, but @file{time.h} was not
protected against multiple inclusion, so programs could not explicitly
include both files. This macro is useful in programs that use, for
example, @code{struct timeval} as well as
@code{struct tm}. It is best used in conjunction with
@code{HAVE_SYS_TIME_H}, which can be checked for using
@code{AC_CHECK_HEADERS([sys/time.h])}.
@example
@group
#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 group
@end example
@noindent
This macro caches its result in the @code{ac_cv_header_time} variable.
This macro is obsolescent, as current systems can include both files
when they exist. New programs need not use this macro.
@end defmac
@defmac AC_HEADER_TIOCGWINSZ
@acindex{HEADER_TIOCGWINSZ}
@cvindex GWINSZ_IN_SYS_IOCTL
@hdrindex{sys/ioctl.h}
@hdrindex{termios.h}
@c FIXME: I need clarifications from Jim.
If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
found in @file{<termios.h>}.
Use:
@example
@group
#ifdef HAVE_TERMIOS_H
# include <termios.h>
#endif
#ifdef GWINSZ_IN_SYS_IOCTL
# include <sys/ioctl.h>
#endif
@end group
@end example
@end defmac
@node Generic Headers
@subsection Generic Header Checks
These macros are used to find system header files not covered by the
``particular'' test macros. If you need to check the contents of a header
as well as find out whether it is present, you have to write your own
test for it (@pxref{Writing Tests}).
@anchor{AC_CHECK_HEADER}
@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @
@ovar{action-if-not-found}, @ovar{includes})
@acindex{CHECK_HEADER}
@caindex header_@var{header-file}
If the system header file @var{header-file} is compilable, 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.
@var{includes} is decoded to determine the appropriate include
directives. If omitted or empty, @file{configure} will check for both header
existence (with the preprocessor) and usability (with the compiler),
using @code{AC_INCLUDES_DEFAULT} for the compile test. If
there is a discrepancy between the results, a warning is issued to the
user, and the compiler results are favored (@pxref{Present But
Cannot Be Compiled}). In general, favoring the compiler results means
that a header will be treated as not found even though the file exists,
because you did not provide enough prerequisites.
Providing a non-empty @var{includes} argument allows the code to provide
any prerequisites prior to including the header under test; it is common
to use the argument @code{AC_INCLUDES_DEFAULT} (@pxref{Default
Includes}). With an explicit fourth argument, no preprocessor test is
needed. As a special case, an @var{includes} of exactly @samp{-}
triggers the older preprocessor check, which merely determines existence
of the file in the preprocessor search path; this should only be used as
a last resort (it is safer to determine the actual prerequisites and
perform a compiler check, or else use @code{AC_PREPROC_IFELSE} to make
it obvious that only a preprocessor check is desired).
This macro caches its result in the @code{ac_cv_header_@var{header-file}}
variable, with characters not suitable for a variable name mapped to
underscores.
@end defmac
@anchor{AC_CHECK_HEADERS}
@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @
@ovar{action-if-found}, @ovar{action-if-not-found}, @
@ovar{includes})
@acindex{CHECK_HEADERS}
@cvindex HAVE_@var{header}
@caindex header_@var{header-file}
For each given system header file @var{header-file} in the
blank-separated argument list that exists, define
@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
is given, it is additional shell code to execute when one of the header
files is found. You can give it a value of @samp{break} to break out of
the loop on the first match. If @var{action-if-not-found} is given, it
is executed when one of the header files is not found.
@var{includes} is interpreted as in @code{AC_CHECK_HEADER}, in order to
choose the set of preprocessor directives supplied before the header
under test.
This macro caches its result in the @code{ac_cv_header_@var{header-file}}
variable, with characters not suitable for a variable name mapped to
underscores.
@end defmac
Previous versions of Autoconf merely checked whether the header was
accepted by the preprocessor. This was changed because the old test was
inappropriate for typical uses. Headers are typically used to compile,
not merely to preprocess, and the old behavior sometimes accepted
headers that clashed at compile-time (@pxref{Present But Cannot Be
Compiled}). If you need to check whether a header is preprocessable,
you can use @code{AC_PREPROC_IFELSE} (@pxref{Running the Preprocessor}).
Actually requiring a header to compile improves the robustness of the
test, but it also requires
that you make sure that headers that must be included before the
@var{header-file} be part of the @var{includes}, (@pxref{Default
Includes}). If looking for @file{bar.h}, which requires that
@file{foo.h} be included before if it exists, we suggest the following
scheme:
@verbatim
AC_CHECK_HEADERS([foo.h])
AC_CHECK_HEADERS([bar.h], [], [],
[#ifdef HAVE_FOO_H
# include <foo.h>
#endif
])
@end verbatim
The following variant generates smaller, faster @command{configure}
files if you do not need the full power of @code{AC_CHECK_HEADERS}.
@defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
@acindex{CHECK_HEADERS_ONCE}
@cvindex HAVE_@var{header}
For each given system header file @var{header-file} in the
blank-separated argument list that exists, define
@code{HAVE_@var{header-file}} (in all capitals).
This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
checking code at most once, so that @command{configure} is smaller and
faster; but the checks cannot be conditionalized and are always done once,
early during the @command{configure} run. Thus, this macro is only safe
for checking headers that do not have prerequisites beyond what
@code{AC_INCLUDES_DEFAULT} provides.
@end defmac
@node Declarations
@section Declarations
@cindex Declaration, checking
The following macros check for the declaration of variables and
functions. If there is no macro specifically defined to check for a
symbol you need, then you can use the general macros (@pxref{Generic
Declarations}) or, for more complex tests, you may use
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
@menu
* Particular Declarations:: Macros to check for certain declarations
* Generic Declarations:: How to find other declarations
@end menu
@node Particular Declarations
@subsection Particular Declaration Checks
There are no specific macros for declarations.
@node Generic Declarations
@subsection Generic Declaration Checks
These macros are used to find declarations not covered by the ``particular''
test macros.
@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_DECL}
@caindex have_decl_@var{symbol}
If @var{symbol} (a function, variable, or constant) is not declared in
@var{includes} and a declaration is needed, run the shell commands
@var{action-if-not-found}, otherwise @var{action-if-found}.
@var{includes} is a series of include directives, defaulting to
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
prior to the declaration under test.
This macro actually tests whether @var{symbol} is defined as a macro or
can be used as an r-value, not whether it is really declared, because it
is much safer to avoid introducing extra declarations when they are not
needed. In order to facilitate use of C++ and overloaded function
declarations, it is possible to specify function argument types in
parentheses for types which can be zero-initialized:
@example
AC_CHECK_DECL([basename(char *)])
@end example
This macro caches its result in the @code{ac_cv_have_decl_@var{symbol}}
variable, with characters not suitable for a variable name mapped to
underscores.
@end defmac
@anchor{AC_CHECK_DECLS}
@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_DECLS}
@cvindex HAVE_DECL_@var{symbol}
@caindex have_decl_@var{symbol}
For each of the @var{symbols} (@emph{comma}-separated list with optional
function argument types for C++ overloads), define
@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
@var{symbol} is declared, otherwise to @samp{0}. If
@var{action-if-not-found} is given, it is additional shell code to
execute when one of the function declarations is needed, otherwise
@var{action-if-found} is executed.
@var{includes} is a series of include directives, defaulting to
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
prior to the declarations under test.
This macro uses an M4 list as first argument:
@example
AC_CHECK_DECLS([strdup])
AC_CHECK_DECLS([strlen])
AC_CHECK_DECLS([malloc, realloc, calloc, free])
AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]])
AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]])
@end example
Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
@emph{sure} that the check was performed, use
@code{HAVE_DECL_@var{symbol}} in @code{#if}:
@example
#if !HAVE_DECL_SYMBOL
extern char *symbol;
#endif
@end example
@noindent
If the test may have not been performed, however, because it is safer
@emph{not} to declare a symbol than to use a declaration that conflicts
with the system's one, you should use:
@example
#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
void *malloc (size_t *s);
#endif
@end example
@noindent
You fall into the second category only in extreme situations: either
your files may be used without being configured, or they are used during
the configuration. In most cases the traditional approach is enough.
This macro caches its results in @code{ac_cv_have_decl_@var{symbol}}
variables, with characters not suitable for a variable name mapped to
underscores.
@end defmac
@defmac AC_CHECK_DECLS_ONCE (@var{symbols})
@acindex{CHECK_DECLS_ONCE}
@cvindex HAVE_DECL_@var{symbol}
For each of the @var{symbols} (@emph{comma}-separated list), define
@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
@var{symbol} is declared in the default include files, otherwise to
@samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
generates the checking code at most once, so that @command{configure} is
smaller and faster; but the checks cannot be conditionalized and are
always done once, early during the @command{configure} run.
@end defmac
@node Structures
@section Structures
@cindex Structure, checking
The following macros check for the presence of certain members in C
structures. If there is no macro specifically defined to check for a
member you need, then you can use the general structure-member macros
(@pxref{Generic Structures}) or, for more complex tests, you may use
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
@menu
* Particular Structures:: Macros to check for certain structure members
* Generic Structures:: How to find other structure members
@end menu
@node Particular Structures
@subsection Particular Structure Checks
The following macros check for certain structures or structure members.
@defmac AC_STRUCT_DIRENT_D_INO
@acindex{STRUCT_DIRENT_D_INO}
@cvindex HAVE_STRUCT_DIRENT_D_INO
@c @caindex header_dirent_dirent_h
@c @caindex member_struct_dirent_d_ino
Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
@code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
@code{d_ino}, not whether its contents are always reliable.
Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
though current systems hide this detail from the user and never return
zero @code{d_ino} values.
Many current systems report an incorrect @code{d_ino} for a directory
entry that is a mount point.
@end defmac
@defmac AC_STRUCT_DIRENT_D_TYPE
@acindex{STRUCT_DIRENT_D_TYPE}
@cvindex HAVE_STRUCT_DIRENT_D_TYPE
@c @caindex header_dirent_dirent_h
@c @caindex member_struct_dirent_d_type
Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
Headers}). Then, if @code{struct dirent} contains a @code{d_type}
member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
@end defmac
@anchor{AC_STRUCT_ST_BLOCKS}
@defmac AC_STRUCT_ST_BLOCKS
@acindex{STRUCT_ST_BLOCKS}
@cvindex HAVE_STRUCT_STAT_ST_BLOCKS
@cvindex HAVE_ST_BLOCKS
@ovindex LIBOBJS
@caindex member_struct_stat_st_blocks
If @code{struct stat} contains an @code{st_blocks} member, define
@code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
future.
This macro caches its result in the @code{ac_cv_member_struct_stat_st_blocks}
variable.
@end defmac
@defmac AC_STRUCT_TM
@acindex{STRUCT_TM}
@cvindex TM_IN_SYS_TIME
@hdrindex{time.h}
@hdrindex{sys/time.h}
If @file{time.h} does not define @code{struct tm}, define
@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
had better define @code{struct tm}.
This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
current systems. New programs need not use this macro.
@end defmac
@anchor{AC_STRUCT_TIMEZONE}
@defmac AC_STRUCT_TIMEZONE
@acindex{STRUCT_TIMEZONE}
@cvindex HAVE_DECL_TZNAME
@cvindex HAVE_STRUCT_TM_TM_ZONE
@cvindex HAVE_TM_ZONE
@cvindex HAVE_TZNAME
@c @caindex member_struct_tm_tm_zone
@c @caindex struct_tm
Figure out how to get the current timezone. If @code{struct tm} has a
@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
@code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
define @code{HAVE_DECL_TZNAME}.
@end defmac
@node Generic Structures
@subsection Generic Structure Checks
These macros are used to find structure members not covered by the
``particular'' test macros.
@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @
@ovar{action-if-found}, @ovar{action-if-not-found}, @
@dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_MEMBER}
@caindex member_@var{aggregate}_@var{member}
Check whether @var{member} is a member of the aggregate @var{aggregate}.
If no @var{includes} are specified, the default includes are used
(@pxref{Default Includes}).
@example
AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
[AC_MSG_ERROR([we need `passwd.pw_gecos'])],
[[#include <pwd.h>]])
@end example
You can use this macro for submembers:
@example
AC_CHECK_MEMBER(struct top.middle.bot)
@end example
This macro caches its result in the
@code{ac_cv_member_@var{aggregate}_@var{member}} variable, with
characters not suitable for a variable name mapped to underscores.
@end defmac
@anchor{AC_CHECK_MEMBERS}
@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_MEMBERS}
@cvindex HAVE_@var{aggregate}_@var{member}
Check for the existence of each @samp{@var{aggregate}.@var{member}} of
@var{members} using the previous macro. When @var{member} belongs to
@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
capitals, with spaces and dots replaced by underscores). If
@var{action-if-found} is given, it is executed for each of the found
members. If @var{action-if-not-found} is given, it is executed for each
of the members that could not be found.
@var{includes} is a series of include directives, defaulting to
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
prior to the members under test.
This macro uses M4 lists:
@example
AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
@end example
@end defmac
@node Types
@section Types
@cindex Types
@cindex C types
The following macros check for C types, either builtin or typedefs. 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 a general type-check macro.
@menu
* Particular Types:: Special handling to find certain types
* Generic Types:: How to find other types
@end menu
@node Particular Types
@subsection Particular Type Checks
@hdrindex{sys/types.h}
@hdrindex{stdlib.h}
@hdrindex{stdint.h}
@hdrindex{inttypes.h}
These macros check for particular C types in @file{sys/types.h},
@file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
exist.
The Gnulib @code{stdint} module is an alternate way to define many of
these symbols; it is useful if you prefer your code to assume a
C99-or-better environment. @xref{Gnulib}.
@anchor{AC_TYPE_GETGROUPS}
@defmac AC_TYPE_GETGROUPS
@acindex{TYPE_GETGROUPS}
@cvindex GETGROUPS_T
@caindex type_getgroups
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}.
This macro caches the base type in the @code{ac_cv_type_getgroups}
variable.
@end defmac
@defmac AC_TYPE_INT8_T
@acindex{TYPE_INT8_T}
@cvindex HAVE_INT8_T
@cvindex int8_t
@caindex c_int8_t
If @file{stdint.h} or @file{inttypes.h} does not define the type
@code{int8_t}, define @code{int8_t} to a signed
integer type that is exactly 8 bits wide and that uses two's complement
representation, if such a type exists.
If you are worried about porting to hosts that lack such a type, you can
use the results of this macro in C89-or-later code as follows:
@example
#if HAVE_STDINT_H
# include <stdint.h>
#endif
#if defined INT8_MAX || defined int8_t
@emph{code using int8_t}
#else
@emph{complicated alternative using >8-bit 'signed char'}
#endif
@end example
This macro caches the type in the @code{ac_cv_c_int8_t} variable.
@end defmac
@defmac AC_TYPE_INT16_T
@acindex{TYPE_INT16_T}
@cvindex HAVE_INT16_T
@cvindex int16_t
@caindex c_int16_t
This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
@end defmac
@defmac AC_TYPE_INT32_T
@acindex{TYPE_INT32_T}
@cvindex HAVE_INT32_T
@cvindex int32_t
@caindex c_int32_t
This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
@end defmac
@defmac AC_TYPE_INT64_T
@acindex{TYPE_INT64_T}
@cvindex HAVE_INT64_T
@cvindex int64_t
@caindex c_int64_t
This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
@end defmac
@defmac AC_TYPE_INTMAX_T
@acindex{TYPE_INTMAX_T}
@cvindex HAVE_INTMAX_T
@cvindex intmax_t
@c @caindex type_intmax_t
If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
widest signed integer type.
@end defmac
@defmac AC_TYPE_INTPTR_T
@acindex{TYPE_INTPTR_T}
@cvindex HAVE_INTPTR_T
@cvindex intptr_t
@c @caindex type_intptr_t
If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
signed integer type wide enough to hold a pointer, if such a type
exists.
@end defmac
@defmac AC_TYPE_LONG_DOUBLE
@acindex{TYPE_LONG_DOUBLE}
@cvindex HAVE_LONG_DOUBLE
@caindex type_long_double
If the C compiler supports a working @code{long double} type, define
@code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
same range and precision as @code{double}.
This macro caches its result in the @code{ac_cv_type_long_double}
variable.
This macro is obsolescent, as current C compilers support @code{long
double}. New programs need not use this macro.
@end defmac
@defmac AC_TYPE_LONG_DOUBLE_WIDER
@acindex{TYPE_LONG_DOUBLE_WIDER}
@cvindex HAVE_LONG_DOUBLE_WIDER
@caindex type_long_double_wider
If the C compiler supports a working @code{long double} type with more
range or precision than the @code{double} type, define
@code{HAVE_LONG_DOUBLE_WIDER}.
This macro caches its result in the @code{ac_cv_type_long_double_wider}
variable.
@end defmac
@defmac AC_TYPE_LONG_LONG_INT
@acindex{TYPE_LONG_LONG_INT}
@cvindex HAVE_LONG_LONG_INT
@caindex type_long_long_int
If the C compiler supports a working @code{long long int} type, define
@code{HAVE_LONG_LONG_INT}. However, this test does not test
@code{long long int} values in preprocessor @code{#if} expressions,
because too many compilers mishandle such expressions.
@xref{Preprocessor Arithmetic}.
This macro caches its result in the @code{ac_cv_type_long_long_int}
variable.
@end defmac
@defmac AC_TYPE_MBSTATE_T
@acindex{TYPE_MBSTATE_T}
@cvindex mbstate_t
@hdrindex{wchar.h}
@caindex type_mbstate_t
Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
@code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
@code{<wchar.h>} does not declare it.
This macro caches its result in the @code{ac_cv_type_mbstate_t}
variable.
@end defmac
@anchor{AC_TYPE_MODE_T}
@defmac AC_TYPE_MODE_T
@acindex{TYPE_MODE_T}
@cvindex mode_t
@caindex type_mode_t
Define @code{mode_t} to a suitable type, if standard headers do not
define it.
This macro caches its result in the @code{ac_cv_type_mode_t} variable.
@end defmac
@anchor{AC_TYPE_OFF_T}
@defmac AC_TYPE_OFF_T
@acindex{TYPE_OFF_T}
@cvindex off_t
@caindex type_off_t
Define @code{off_t} to a suitable type, if standard headers do not
define it.
This macro caches its result in the @code{ac_cv_type_off_t} variable.
@end defmac
@anchor{AC_TYPE_PID_T}
@defmac AC_TYPE_PID_T
@acindex{TYPE_PID_T}
@cvindex pid_t
@caindex type_pid_t
Define @code{pid_t} to a suitable type, if standard headers do not
define it.
This macro caches its result in the @code{ac_cv_type_pid_t} variable.
@end defmac
@anchor{AC_TYPE_SIZE_T}
@defmac AC_TYPE_SIZE_T
@acindex{TYPE_SIZE_T}
@cvindex size_t
@caindex type_size_t
Define @code{size_t} to a suitable type, if standard headers do not
define it.
This macro caches its result in the @code{ac_cv_type_size_t} variable.
@end defmac
@defmac AC_TYPE_SSIZE_T
@acindex{TYPE_SSIZE_T}
@cvindex ssize_t
@caindex type_ssize_t
Define @code{ssize_t} to a suitable type, if standard headers do not
define it.
This macro caches its result in the @code{ac_cv_type_ssize_t} variable.
@end defmac
@anchor{AC_TYPE_UID_T}
@defmac AC_TYPE_UID_T
@acindex{TYPE_UID_T}
@cvindex uid_t
@cvindex gid_t
@caindex type_uid_t
Define @code{uid_t} and @code{gid_t} to suitable types, if standard
headers do not define them.
This macro caches its result in the @code{ac_cv_type_uid_t} variable.
@end defmac
@defmac AC_TYPE_UINT8_T
@acindex{TYPE_UINT8_T}
@cvindex HAVE_UINT8_T
@cvindex uint8_t
@caindex c_uint8_t
If @file{stdint.h} or @file{inttypes.h} does not define the type
@code{uint8_t}, define @code{uint8_t} to an
unsigned integer type that is exactly 8 bits wide, if such a type
exists.
This is like @code{AC_TYPE_INT8_T}, except for unsigned integers.
@end defmac
@defmac AC_TYPE_UINT16_T
@acindex{TYPE_UINT16_T}
@cvindex HAVE_UINT16_T
@cvindex uint16_t
@caindex c_uint16_t
This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers.
@end defmac
@defmac AC_TYPE_UINT32_T
@acindex{TYPE_UINT32_T}
@cvindex HAVE_UINT32_T
@cvindex uint32_t
@caindex c_uint32_t
This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers.
@end defmac
@defmac AC_TYPE_UINT64_T
@acindex{TYPE_UINT64_T}
@cvindex HAVE_UINT64_T
@cvindex uint64_t
@caindex c_uint64_t
This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers.
@end defmac
@defmac AC_TYPE_UINTMAX_T
@acindex{TYPE_UINTMAX_T}
@cvindex HAVE_UINTMAX_T
@cvindex uintmax_t
@c @caindex type_uintmax_t
If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
widest unsigned integer type.
@end defmac
@defmac AC_TYPE_UINTPTR_T
@acindex{TYPE_UINTPTR_T}
@cvindex HAVE_UINTPTR_T
@cvindex uintptr_t
@c @caindex type_uintptr_t
If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
unsigned integer type wide enough to hold a pointer, if such a type
exists.
@end defmac
@defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
@acindex{TYPE_UNSIGNED_LONG_LONG_INT}
@cvindex HAVE_UNSIGNED_LONG_LONG_INT
@caindex type_unsigned_long_long_int
If the C compiler supports a working @code{unsigned long long int} type,
define @code{HAVE_UNSIGNED_LONG_LONG_INT}. However, this test does not test
@code{unsigned long long int} values in preprocessor @code{#if} expressions,
because too many compilers mishandle such expressions.
@xref{Preprocessor Arithmetic}.
This macro caches its result in the @code{ac_cv_type_unsigned_long_long_int}
variable.
@end defmac
@node Generic Types
@subsection Generic Type Checks
These macros are used to check for types not covered by the ``particular''
test macros.
@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_TYPE}
@caindex type_@var{type}
Check whether @var{type} is defined. It may be a compiler builtin type
or defined by the @var{includes}. @var{includes} is a series of include
directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default
Includes}), which are used prior to the type under test.
In C, @var{type} must be a type-name, so that the expression @samp{sizeof
(@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The
same test is applied when compiling for C++, which means that in C++
@var{type} should be a type-id and should not be an anonymous
@samp{struct} or @samp{union}.
This macro caches its result in the @code{ac_cv_type_@var{type}}
variable, with @samp{*} mapped to @samp{p} and other characters not
suitable for a variable name mapped to underscores.
@end defmac
@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_TYPES}
@cvindex HAVE_@var{type}
For each @var{type} of the @var{types} that is defined, define
@code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow
the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are
specified, the default includes are used (@pxref{Default Includes}). If
@var{action-if-found} is given, it is additional shell code to execute
when one of the types is found. If @var{action-if-not-found} is given,
it is executed when one of the types is not found.
This macro uses M4 lists:
@example
AC_CHECK_TYPES([ptrdiff_t])
AC_CHECK_TYPES([unsigned long long int, uintmax_t])
AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]])
@end example
@end defmac
Autoconf, up to 2.13, used to provide to another version of
@code{AC_CHECK_TYPE}, broken by design. In order to keep backward
compatibility, a simple heuristic, quite safe but not totally, is
implemented. In case of doubt, read the documentation of the former
@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
@node Compilers and Preprocessors
@section Compilers and Preprocessors
@cindex Compilers
@cindex Preprocessors
@ovindex EXEEXT
All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
the output of the compiler, typically to the empty string if
Posix and @samp{.exe} if a DOS variant.
@ovindex OBJEXT
They also define the output variable @code{OBJEXT} based on the
output of the compiler, after @file{.c} files have been excluded, typically
to @samp{o} if Posix, @samp{obj} if a DOS variant.
If the compiler being used does not produce executables, the tests fail. If
the executables can't be run, and cross-compilation is not enabled, they
fail too. @xref{Manual Configuration}, for more on support for cross
compiling.
@menu
* Specific Compiler Characteristics:: Some portability issues
* Generic Compiler Characteristics:: Language independent tests and features
* C Compiler:: Checking its characteristics
* C++ Compiler:: Likewise
* Objective C Compiler:: Likewise
* Objective C++ Compiler:: Likewise
* Erlang Compiler and Interpreter:: Likewise
* Fortran Compiler:: Likewise
* Go Compiler:: Likewise
@end menu
@node Specific Compiler Characteristics
@subsection Specific Compiler Characteristics
Some compilers exhibit different behaviors.
@table @asis
@item Static/Dynamic Expressions
Autoconf relies on a trick to extract one bit of information from the C
compiler: using negative array sizes. For instance the following
excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
bytes wide:
@example
static int test_array[sizeof (int) == 4 ? 1 : -1];
@end example
@noindent
To our knowledge, there is a single compiler that does not support this
trick: the HP C compilers (the real ones, not only the
``bundled'') on HP-UX 11.00.
They incorrectly reject the above program with the diagnostic
``Variable-length arrays cannot have static storage.''
This bug comes from HP compilers' mishandling of @code{sizeof (int)},
not from the @code{? 1 : -1}, and
Autoconf works around this problem by casting @code{sizeof (int)} to
@code{long int} before comparing it.
@end table
@node Generic Compiler Characteristics
@subsection Generic Compiler Characteristics
@anchor{AC_CHECK_SIZEOF}
@defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @
@dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_SIZEOF}
@cvindex SIZEOF_@var{type-or-expr}
@caindex sizeof_@var{type-or-expr}
Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be
the size in bytes of @var{type-or-expr}, which may be either a type or
an expression returning a value that has a size. If the expression
@samp{sizeof (@var{type-or-expr})} is invalid, the result is 0.
@var{includes} is a series of include directives, defaulting to
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
prior to the expression under test.
This macro now works even when cross-compiling. The @var{unused}
argument was used when cross-compiling.
For example, the call
@example
@c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct.
AC_CHECK_SIZEOF([int *])
@end example
@noindent
defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
This macro caches its result in the @code{ac_cv_sizeof_@var{type-or-expr}}
variable, with @samp{*} mapped to @samp{p} and other characters not
suitable for a variable name mapped to underscores.
@end defmac
@defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, AC_INCLUDES_DEFAULT})
@acindex{CHECK_ALIGNOF}
@cvindex ALIGNOF_@var{type}
@caindex alignof_@var{type-or-expr}
Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as
a structure member declaration. If @samp{type} is unknown, the result
is 0. If no @var{includes} are specified, the default includes are used
(@pxref{Default Includes}).
This macro caches its result in the @code{ac_cv_alignof_@var{type-or-expr}}
variable, with @samp{*} mapped to @samp{p} and other characters not
suitable for a variable name mapped to underscores.
@end defmac
@defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @
@dvar{includes, AC_INCLUDES_DEFAULT}, @ovar{action-if-fails})
@acindex{COMPUTE_INT}
Store into the shell variable @var{var} the value of the integer
@var{expression}. The
value should fit in an initializer in a C variable of type @code{signed
long}. To support cross compilation (in which case, the macro only works on
hosts that use twos-complement arithmetic), it should be possible to evaluate
the expression at compile-time. If no @var{includes} are specified, the
default includes are used (@pxref{Default Includes}).
Execute @var{action-if-fails} if the value cannot be determined correctly.
@end defmac
@defmac AC_LANG_WERROR
@acindex{LANG_WERROR}
Normally Autoconf ignores warnings generated by the compiler, linker, and
preprocessor. If this macro is used, warnings count as fatal
errors for the current language. This macro is useful when the
results of configuration are used where warnings are unacceptable; for
instance, if parts of a program are built with the GCC
@option{-Werror}
option. If the whole program is built using @option{-Werror} it is
often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
etc.).
@end defmac
@defmac AC_OPENMP
@acindex{OPENMP}
@cvindex _OPENMP
@ovindex OPENMP_CFLAGS
@ovindex OPENMP_CXXFLAGS
@ovindex OPENMP_FFLAGS
@ovindex OPENMP_FCFLAGS
@caindex prog_c_openmp
@caindex prog_cxx_openmp
@caindex prog_f77_openmp
@caindex prog_fc_openmp
@uref{http://@/www.openmp.org/, OpenMP} specifies extensions of C, C++,
and Fortran that simplify optimization of shared memory parallelism,
which is a common problem on multicore CPUs.
If the current language is C, the macro @code{AC_OPENMP} sets the
variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the
compiler already supports OpenMP, if it has no way to activate OpenMP
support, or if the user rejects OpenMP support by invoking
@samp{configure} with the @samp{--disable-openmp} option.
@code{OPENMP_CFLAGS} needs to be used when compiling programs, when
preprocessing program source, and when linking programs. Therefore you
need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
that use OpenMP@. If you preprocess OpenMP-specific C code, you also
need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of
OpenMP support is revealed at compile time by the preprocessor macro
@code{_OPENMP}.
Linking a program with @code{OPENMP_CFLAGS} typically adds one more
shared library to the program's dependencies, so its use is recommended
only on programs that actually require OpenMP.
If the current language is C++, @code{AC_OPENMP} sets the variable
@code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks
hold as for C.
If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
respectively. Similar remarks as for C hold, except that
@code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
signals OpenMP support.
For portability, it is best to avoid spaces between @samp{#} and
@samp{pragma omp}. That is, write @samp{#pragma omp}, not
@samp{# pragma omp}. The Sun WorkShop 6.2 C compiler chokes on the
latter.
This macro caches its result in the @code{ac_cv_prog_c_openmp},
@code{ac_cv_prog_cxx_openmp}, @code{ac_cv_prog_f77_openmp}, or
@code{ac_cv_prog_fc_openmp} variable, depending on the current language.
@end defmac
@node C Compiler
@subsection C Compiler Characteristics
The following macros provide ways to find and exercise a C Compiler.
There are a few constructs that ought to be avoided, but do not deserve
being checked for, since they can easily be worked around.
@table @asis
@item Don't use lines containing solitary backslashes
They tickle a bug in the HP-UX C compiler (checked on
HP-UX 10.20,
11.00, and 11i). When given the following source:
@example
#ifdef __STDC__
/\
* A comment with backslash-newlines in it. %@{ %@} *\
\
/
char str[] = "\\
" A string with backslash-newlines in it %@{ %@} \\
"";
char apostrophe = '\\
\
'\
';
#endif
@end example
@noindent
the compiler incorrectly fails with the diagnostics ``Non-terminating
comment at end of file'' and ``Missing @samp{#endif} at end of file.''
Removing the lines with solitary backslashes solves the problem.
@item Don't compile several files at once if output matters to you
Some compilers, such as HP's, report names of files being
compiled when given more than one file operand. For instance:
@example
$ @kbd{cc a.c b.c}
a.c:
b.c:
@end example
@noindent
This can cause problems if you observe the output of the compiler to
detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
b.o} solves the issue.
@item Don't rely on @code{#error} failing
The IRIX C compiler does not fail when #error is preprocessed; it
simply emits a diagnostic and continues, exiting successfully. So,
instead of an error directive like @code{#error "Unsupported word size"}
it is more portable to use an invalid directive like @code{#Unsupported
word size} in Autoconf tests. In ordinary source code, @code{#error} is
OK, since installers with inadequate compilers like IRIX can simply
examine these compilers' diagnostic output.
@item Don't rely on correct @code{#line} support
On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
diagnoses @code{#line} directives whose line
numbers are greater than 32767. Nothing in Posix
makes this invalid. That is why Autoconf stopped issuing
@code{#line} directives.
@end table
@defmac AC_PROG_CC (@ovar{compiler-search-list})
@acindex{PROG_CC}
@evindex CC
@evindex CFLAGS
@ovindex CC
@ovindex CFLAGS
@caindex prog_cc_c89
Determine a C compiler to use. If @code{CC} is not already set in the
environment, check for @code{gcc} and @code{cc}, then for other C
compilers. Set output variable @code{CC} to the name of the compiler
found.
This macro may, however, be invoked with an optional first argument
which, if specified, must be a blank-separated list of C compilers to
search for. This just gives the user an opportunity to specify an
alternative search list for the C compiler. For example, if you didn't
like the default order, then you could invoke @code{AC_PROG_CC} like
this:
@example
AC_PROG_CC([gcc cl cc])
@end example
If the C compiler does not handle function prototypes correctly by
default, try to add an option to output variable @code{CC} to make it
so. This macro tries various options that select standard-conformance
modes on various systems.
After calling this macro you can check whether the C compiler has been
set to accept ANSI C89 (ISO C90); if not, the shell
variable
@code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
@code{AC_C_PROTOTYPES} below.
If using the GNU C compiler, set shell variable @code{GCC} to
@samp{yes}. If output variable @code{CFLAGS} was not already set, set
it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems
where GCC does not accept @option{-g}), or @option{-g} for
other compilers. If your package does not like this default, then it is
acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT}
and before @code{AC_PROG_CC} to select an empty default instead.
Many Autoconf macros use a compiler, and thus call
@samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been
determined before the body of the outermost @code{AC_DEFUN} macro.
Although @code{AC_PROG_CC} is safe to directly expand multiple times, it
performs certain checks (such as the proper value of @env{EXEEXT}) only
on the first invocation. Therefore, care must be used when invoking
this macro from within another macro rather than at the top level
(@pxref{Expanded Before Required}).
@end defmac
@anchor{AC_PROG_CC_C_O}
@defmac AC_PROG_CC_C_O
@acindex{PROG_CC_C_O}
@cvindex NO_MINUS_C_MINUS_O
@caindex prog_cc_@var{compiler}_c_o
If the C compiler does not accept the @option{-c} and @option{-o} options
simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
tests both the compiler found by @code{AC_PROG_CC}, and, if different,
the first @code{cc} in the path. The test fails if one fails. This
macro was created for GNU Make to choose the default C compilation
rule.
For the compiler @var{compiler}, this macro caches its result in the
@code{ac_cv_prog_cc_@var{compiler}_c_o} variable.
@end defmac
@defmac AC_PROG_CPP
@acindex{PROG_CPP}
@evindex CPP
@ovindex CPP
Set output variable @code{CPP} to a command that runs the
C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
It is only portable to run @code{CPP} on files with a @file{.c}
extension.
Some preprocessors don't indicate missing include files by the error
status. For such preprocessors an internal variable is set that causes
other macros to check the standard error from the preprocessor and
consider the test failed if any warnings have been reported.
For most preprocessors, though, warnings do not cause include-file
tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
@end defmac
@defmac AC_PROG_CPP_WERROR
@acindex{PROG_CPP_WERROR}
@ovindex CPP
This acts like @code{AC_PROG_CPP}, except it treats warnings from the
preprocessor as errors even if the preprocessor exit status indicates
success. This is useful for avoiding headers that generate mandatory
warnings, such as deprecation notices.
@end defmac
The following macros check for C compiler or machine architecture
features. To check for characteristics not listed here, use
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
@code{AC_RUN_IFELSE} (@pxref{Runtime}).
@defmac AC_PROG_CC_STDC
@acindex{PROG_CC_STDC}
@caindex prog_cc_stdc
If the C compiler cannot compile ISO Standard C (currently
C99), try to add an option to output variable @code{CC} to make it work.
If the compiler does not support C99, fall back to supporting
ANSI C89 (ISO C90).
After calling this macro you can check whether the C compiler has been
set to accept Standard C; if not, the shell variable
@code{ac_cv_prog_cc_stdc} is set to @samp{no}.
@end defmac
@defmac AC_PROG_CC_C89
@acindex{PROG_CC_C89}
@caindex prog_cc_c89
If the C compiler is not in ANSI C89 (ISO C90) mode by
default, try to add an option to output variable @code{CC} to make it
so. This macro tries various options that select ANSI C89 on
some system or another, preferring extended functionality modes over
strict conformance modes. It considers the compiler to be in
ANSI C89 mode if it handles function prototypes correctly.
After calling this macro you can check whether the C compiler has been
set to accept ANSI C89; if not, the shell variable
@code{ac_cv_prog_cc_c89} is set to @samp{no}.
This macro is called automatically by @code{AC_PROG_CC}.
@end defmac
@defmac AC_PROG_CC_C99
@acindex{PROG_CC_C99}
@caindex prog_cc_c99
If the C compiler is not in C99 mode by default, try to add an
option to output variable @code{CC} to make it so. This macro tries
various options that select C99 on some system or another, preferring
extended functionality modes over strict conformance modes. It
considers the compiler to be in C99 mode if it handles @code{_Bool},
@code{//} comments, flexible array members, @code{inline}, signed and
unsigned @code{long long int}, mixed code and declarations, named
initialization of structs,
@code{restrict}, @code{va_copy}, varargs macros, variable declarations
in @code{for} loops, and variable length arrays.
After calling this macro you can check whether the C compiler has been
set to accept C99; if not, the shell variable
@code{ac_cv_prog_cc_c99} is set to @samp{no}.
@end defmac
@defmac AC_C_BACKSLASH_A
@acindex{C_BACKSLASH_A}
@cvindex HAVE_C_BACKSLASH_A
Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
@samp{\a}.
This macro is obsolescent, as current C compilers understand @samp{\a}.
New programs need not use this macro.
@end defmac
@anchor{AC_C_BIGENDIAN}
@defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @
@ovar{action-if-unknown}, @ovar{action-if-universal})
@acindex{C_BIGENDIAN}
@cvindex WORDS_BIGENDIAN
@cindex Endianness
If words are stored with the most significant byte first (like Motorola
and SPARC CPUs), execute @var{action-if-true}. If words are stored with
the least significant byte first (like Intel and VAX CPUs), execute
@var{action-if-false}.
This macro runs a test-case if endianness cannot be determined from the
system header files. When cross-compiling, the test-case is not run but
grep'ed for some magic values. @var{action-if-unknown} is executed if
the latter case fails to determine the byte sex of the host system.
In some cases a single run of a compiler can generate code for multiple
architectures. This can happen, for example, when generating Mac OS X
universal binary files, which work on both PowerPC and Intel
architectures. In this case, the different variants might be for
different architectures whose endiannesses differ. If
@command{configure} detects this, it executes @var{action-if-universal}
instead of @var{action-if-unknown}.
The default for @var{action-if-true} is to define
@samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
nothing. The default for @var{action-if-unknown} is to
abort configure and tell the installer how to bypass this test.
And finally, the default for @var{action-if-universal} is to ensure that
@samp{WORDS_BIGENDIAN} is defined if and only if a universal build is
detected and the current code is big-endian; this default works only if
@command{autoheader} is used (@pxref{autoheader Invocation}).
If you use this macro without specifying @var{action-if-universal}, you
should also use @code{AC_CONFIG_HEADERS}; otherwise
@samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
binary files.
@end defmac
@anchor{AC_C_CONST}
@defmac AC_C_CONST
@acindex{C_CONST}
@cvindex const
@caindex c_const
If the C compiler does not fully support the @code{const} keyword,
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 makefile or configuration header file
defines it as empty.
Occasionally installers use a C++ compiler to compile C code, typically
because they lack a C compiler. This causes problems with @code{const},
because C and C++ treat @code{const} differently. For example:
@example
const int foo;
@end example
@noindent
is valid in C but not in C++. These differences unfortunately cannot be
papered over by defining @code{const} to be empty.
If @command{autoconf} detects this situation, it leaves @code{const} alone,
as this generally yields better results in practice. However, using a
C++ compiler to compile C code is not recommended or supported, and
installers who run into trouble in this area should get a C compiler
like GCC to compile their C code.
This macro caches its result in the @code{ac_cv_c_const} variable.
This macro is obsolescent, as current C compilers support @code{const}.
New programs need not use this macro.
@end defmac
@defmac AC_C_RESTRICT
@acindex{C_RESTRICT}
@cvindex restrict
@caindex c_restrict
If the C compiler recognizes a variant spelling for the @code{restrict}
keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
then define @code{restrict} to that; this is more likely to do the right
thing with compilers that support language variants where plain
@code{restrict} is not a keyword. Otherwise, if the C compiler
recognizes the @code{restrict} keyword, don't do anything.
Otherwise, define @code{restrict} to be empty.
Thus, programs may simply use @code{restrict} as if every C compiler
supported it; for those that do not, the makefile
or configuration header defines it away.
Although support in C++ for the @code{restrict} keyword is not
required, several C++ compilers do accept the keyword.
This macro works for them, too.
This macro caches @samp{no} in the @code{ac_cv_c_restrict} variable
if @code{restrict} is not supported, and a supported spelling otherwise.
@end defmac
@defmac AC_C_VOLATILE
@acindex{C_VOLATILE}
@cvindex volatile
If the C compiler does not understand the keyword @code{volatile},
define @code{volatile} to be empty. Programs can simply use
@code{volatile} as if every C compiler supported it; for those that do
not, the makefile or configuration header defines it as
empty.
If the correctness of your program depends on the semantics of
@code{volatile}, simply defining it to be empty does, in a sense, break
your code. However, given that the compiler does not support
@code{volatile}, you are at its mercy anyway. At least your
program compiles, when it wouldn't before.
@xref{Volatile Objects}, for more about @code{volatile}.
In general, the @code{volatile} keyword is a standard C feature, so
you might expect that @code{volatile} is available only when
@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
support volatile, but does not define @code{__STDC__}.
This macro is obsolescent, as current C compilers support @code{volatile}.
New programs need not use this macro.
@end defmac
@anchor{AC_C_INLINE}
@defmac AC_C_INLINE
@acindex{C_INLINE}
@cvindex inline
If the C compiler supports the keyword @code{inline}, do nothing.
Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
if it accepts one of those, otherwise define @code{inline} to be empty.
@end defmac
@anchor{AC_C_CHAR_UNSIGNED}
@defmac AC_C_CHAR_UNSIGNED
@acindex{C_CHAR_UNSIGNED}
@cvindex __CHAR_UNSIGNED__
If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
unless the C compiler predefines it.
These days, using this macro is not necessary. The same information can
be determined by this portable alternative, thus avoiding the use of
preprocessor macros in the namespace reserved for the implementation.
@example
#include <limits.h>
#if CHAR_MIN == 0
# define CHAR_UNSIGNED 1
#endif
@end example
@end defmac
@defmac AC_C_STRINGIZE
@acindex{C_STRINGIZE}
@cvindex HAVE_STRINGIZE
If the C preprocessor supports the stringizing operator, define
@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
found in macros such as this:
@example
#define x(y) #y
@end example
This macro is obsolescent, as current C compilers support the
stringizing operator. New programs need not use this macro.
@end defmac
@defmac AC_C_FLEXIBLE_ARRAY_MEMBER
@acindex{C_FLEXIBLE_ARRAY_MEMBER}
@cvindex FLEXIBLE_ARRAY_MEMBER
If the C compiler supports flexible array members, define
@code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
That way, a declaration like this:
@example
struct s
@{
size_t n_vals;
double val[FLEXIBLE_ARRAY_MEMBER];
@};
@end example
@noindent
will let applications use the ``struct hack'' even with compilers that
do not support flexible array members. To allocate and use such an
object, you can use code like this:
@example
size_t i;
size_t n = compute_value_count ();
struct s *p =
malloc (offsetof (struct s, val)
+ n * sizeof (double));
p->n_vals = n;
for (i = 0; i < n; i++)
p->val[i] = compute_value (i);
@end example
@end defmac
@defmac AC_C_VARARRAYS
@acindex{C_VARARRAYS}
@cvindex HAVE_C_VARARRAYS
If the C compiler supports variable-length arrays, define
@code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
storage duration whose length is determined at run time, when the array
is declared.
@end defmac
@defmac AC_C_TYPEOF
@acindex{C_TYPEOF}
@cvindex HAVE_TYPEOF
@cvindex typeof
If the C compiler supports GCC's @code{typeof} syntax either
directly or
through a different spelling of the keyword (e.g., @code{__typeof__}),
define @code{HAVE_TYPEOF}. If the support is available only through a
different spelling, define @code{typeof} to that spelling.
@end defmac
@defmac AC_C_PROTOTYPES
@acindex{C_PROTOTYPES}
@cvindex PROTOTYPES
@cvindex __PROTOTYPES
@cvindex PARAMS
If function prototypes are understood by the compiler (as determined by
@code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
Defining @code{__PROTOTYPES} is for the benefit of
header files that cannot use macros that infringe on user name space.
This macro is obsolescent, as current C compilers support prototypes.
New programs need not use this macro.
@end defmac
@anchor{AC_PROG_GCC_TRADITIONAL}
@defmac AC_PROG_GCC_TRADITIONAL
@acindex{PROG_GCC_TRADITIONAL}
@ovindex CC
Add @option{-traditional} to output variable @code{CC} if using the
GNU C compiler and @code{ioctl} does not work properly without
@option{-traditional}. That usually happens when the fixed header files
have not been installed on an old system.
This macro is obsolescent, since current versions of the GNU C
compiler fix the header files automatically when installed.
@end defmac
@node C++ Compiler
@subsection C++ Compiler Characteristics
@defmac AC_PROG_CXX (@ovar{compiler-search-list})
@acindex{PROG_CXX}
@evindex CXX
@evindex CXXFLAGS
@ovindex CXX
@ovindex CXXFLAGS
Determine a C++ compiler to use. Check whether the environment variable
@code{CXX} or @code{CCC} (in that order) is set; if so, then set output
variable @code{CXX} to its value.
Otherwise, if the macro is invoked without an argument, then search for
a C++ compiler under the likely names (first @code{g++} and @code{c++}
then other names). If none of those checks succeed, then as a last
resort set @code{CXX} to @code{g++}.
This macro may, however, be invoked with an optional first argument
which, if specified, must be a blank-separated list of C++ compilers to
search for. This just gives the user an opportunity to specify an
alternative search list for the C++ compiler. For example, if you
didn't like the default order, then you could invoke @code{AC_PROG_CXX}
like this:
@example
AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
@end example
If using the GNU C++ compiler, set shell variable @code{GXX} to
@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on
systems where G++ does not accept @option{-g}), or @option{-g} for other
compilers. If your package does not like this default, then it is
acceptable to insert the line @samp{: $@{CXXFLAGS=""@}} after @code{AC_INIT}
and before @code{AC_PROG_CXX} to select an empty default instead.
@end defmac
@defmac AC_PROG_CXXCPP
@acindex{PROG_CXXCPP}
@evindex CXXCPP
@ovindex CXXCPP
Set output variable @code{CXXCPP} to a command that runs the C++
preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
It is portable to run @code{CXXCPP} only on files with a @file{.c},
@file{.C}, @file{.cc}, or @file{.cpp} extension.
Some preprocessors don't indicate missing include files by the error
status. For such preprocessors an internal variable is set that causes
other macros to check the standard error from the preprocessor and
consider the test failed if any warnings have been reported. However,
it is not known whether such broken preprocessors exist for C++.
@end defmac
@defmac AC_PROG_CXX_C_O
@acindex{PROG_CXX_C_O}
@cvindex CXX_NO_MINUS_C_MINUS_O
Test whether the C++ compiler accepts the options @option{-c} and
@option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
if it does not.
@end defmac
@node Objective C Compiler
@subsection Objective C Compiler Characteristics
@defmac AC_PROG_OBJC (@ovar{compiler-search-list})
@acindex{PROG_OBJC}
@evindex OBJC
@evindex OBJCFLAGS
@ovindex OBJC
@ovindex OBJCFLAGS
Determine an Objective C compiler to use. If @code{OBJC} is not already
set in the environment, check for Objective C compilers. Set output
variable @code{OBJC} to the name of the compiler found.
This macro may, however, be invoked with an optional first argument
which, if specified, must be a blank-separated list of Objective C compilers to
search for. This just gives the user an opportunity to specify an
alternative search list for the Objective C compiler. For example, if you
didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
like this:
@example
AC_PROG_OBJC([gcc objcc objc])
@end example
If using the GNU Objective C compiler, set shell variable
@code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
already set, set it to @option{-g -O2} for the GNU Objective C
compiler (@option{-O2} on systems where @command{gcc} does not accept
@option{-g}), or @option{-g} for other compilers.
@end defmac
@defmac AC_PROG_OBJCPP
@acindex{PROG_OBJCPP}
@evindex OBJCPP
@ovindex OBJCPP
Set output variable @code{OBJCPP} to a command that runs the Objective C
preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
@end defmac
@node Objective C++ Compiler
@subsection Objective C++ Compiler Characteristics
@defmac AC_PROG_OBJCXX (@ovar{compiler-search-list})
@acindex{PROG_OBJCXX}
@evindex OBJCXX
@evindex OBJCXXFLAGS
@ovindex OBJCXX
@ovindex OBJCXXFLAGS
Determine an Objective C++ compiler to use. If @code{OBJCXX} is not already
set in the environment, check for Objective C++ compilers. Set output
variable @code{OBJCXX} to the name of the compiler found.
This macro may, however, be invoked with an optional first argument
which, if specified, must be a blank-separated list of Objective C++ compilers
to search for. This just gives the user an opportunity to specify an
alternative search list for the Objective C++ compiler. For example, if you
didn't like the default order, then you could invoke @code{AC_PROG_OBJCXX}
like this:
@example
AC_PROG_OBJCXX([gcc g++ objcc++ objcxx])
@end example
If using the GNU Objective C++ compiler, set shell variable
@code{GOBJCXX} to @samp{yes}. If output variable @code{OBJCXXFLAGS} was not
already set, set it to @option{-g -O2} for the GNU Objective C++
compiler (@option{-O2} on systems where @command{gcc} does not accept
@option{-g}), or @option{-g} for other compilers.
@end defmac
@defmac AC_PROG_OBJCXXCPP
@acindex{PROG_OBJCXXCPP}
@evindex OBJCXXCPP
@ovindex OBJCXXCPP
Set output variable @code{OBJCXXCPP} to a command that runs the Objective C++
preprocessor. If @samp{$OBJCXX -E} doesn't work, @file{/lib/cpp} is used.
@end defmac
@node Erlang Compiler and Interpreter
@subsection Erlang Compiler and Interpreter Characteristics
@cindex Erlang
Autoconf defines the following macros for determining paths to the essential
Erlang/OTP programs:
@defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{ERLANG_PATH_ERLC}
@evindex ERLC
@evindex ERLCFLAGS
@ovindex ERLC
@ovindex ERLCFLAGS
Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
environment, check for @command{erlc}. Set output variable @code{ERLC} to the
complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
is not set in the environment, set it to an empty value.
The two optional arguments have the same meaning as the two last arguments of
macro @code{AC_PATH_PROG} for looking for the @command{erlc} program. For
example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
directory:
@example
AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
@end example
@end defmac
@defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH})
@acindex{ERLANG_NEED_ERLC}
A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
error message and exits the @command{configure} script if the @command{erlc}
program is not found.
@end defmac
@defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH})
@acindex{ERLANG_PATH_ERL}
@evindex ERL
@ovindex ERL
Determine an Erlang interpreter to use. If @code{ERL} is not already
set in the
environment, check for @command{erl}. Set output variable @code{ERL} to the
complete path of the interpreter command found.
The two optional arguments have the same meaning as the two last arguments of
macro @code{AC_PATH_PROG} for looking for the @command{erl} program. For
example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
directory:
@example
AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
@end example
@end defmac
@defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH})
@acindex{ERLANG_NEED_ERL}
A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
error message and exits the @command{configure} script if the @command{erl}
program is not found.
@end defmac
@node Fortran Compiler
@subsection Fortran Compiler Characteristics
@cindex Fortran
@cindex F77
The Autoconf Fortran support is divided into two categories: legacy
Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
The former are intended for traditional Fortran 77 code, and have output
variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
are for newer programs that can (or must) compile under the newer
Fortran standards, and have output variables like @code{FC},
@code{FCFLAGS}, and @code{FCLIBS}.
Except for the macros @code{AC_FC_SRCEXT}, @code{AC_FC_FREEFORM},
@code{AC_FC_FIXEDFORM}, and @code{AC_FC_LINE_LENGTH} (see below), the
@code{FC} and @code{F77} macros behave almost identically, and so they
are documented together in this section.
@defmac AC_PROG_F77 (@ovar{compiler-search-list})
@acindex{PROG_F77}
@evindex F77
@evindex FFLAGS
@ovindex F77
@ovindex FFLAGS
@caindex f77_compiler_gnu
@caindex prog_f77_g
Determine a Fortran 77 compiler to use. If @code{F77} is not already
set in the environment, then check for @code{g77} and @code{f77}, and
then some other names. Set the output variable @code{F77} to the name
of the compiler found.
This macro may, however, be invoked with an optional first argument
which, if specified, must be a blank-separated list of Fortran 77
compilers to search for. This just gives the user an opportunity to
specify an alternative search list for the Fortran 77 compiler. For
example, if you didn't like the default order, then you could invoke
@code{AC_PROG_F77} like this:
@example
AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
@end example
If using @code{g77} (the GNU Fortran 77 compiler), then
set the shell variable @code{G77} to @samp{yes}.
If the output variable @code{FFLAGS} was not already set in the
environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
where @code{g77} does not accept @option{-g}). Otherwise, set
@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
The result of the GNU test is cached in the
@code{ac_cv_f77_compiler_gnu} variable, acceptance of @option{-g} in the
@code{ac_cv_prog_f77_g} variable.
@end defmac
@defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
@acindex{PROG_FC}
@evindex FC
@evindex FCFLAGS
@ovindex FC
@ovindex FCFLAGS
@caindex fc_compiler_gnu
@caindex prog_fc_g
Determine a Fortran compiler to use. If @code{FC} is not already set in
the environment, then @code{dialect} is a hint to indicate what Fortran
dialect to search for; the default is to search for the newest available
dialect. Set the output variable @code{FC} to the name of the compiler
found.
By default, newer dialects are preferred over older dialects, but if
@code{dialect} is specified then older dialects are preferred starting
with the specified dialect. @code{dialect} can currently be one of
Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
and no attempt is made to guarantee that a particular language standard
is actually supported. Thus, it is preferable that you avoid the
@code{dialect} option, and use AC_PROG_FC only for code compatible with
the latest Fortran standard.
This macro may, alternatively, be invoked with an optional first argument
which, if specified, must be a blank-separated list of Fortran
compilers to search for, just as in @code{AC_PROG_F77}.
If using @code{gfortran} or @code{g77} (the GNU Fortran compilers), then
set the shell variable @code{GFC} to @samp{yes}.
If the output variable @code{FCFLAGS} was not already set in the
environment, then set it to @option{-g -02} for GNU @code{g77} (or
@option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
The result of the GNU test is cached in the @code{ac_cv_fc_compiler_gnu}
variable, acceptance of @option{-g} in the @code{ac_cv_prog_fc_g}
variable.
@end defmac
@defmac AC_PROG_F77_C_O
@defmacx AC_PROG_FC_C_O
@acindex{PROG_F77_C_O}
@acindex{PROG_FC_C_O}
@cvindex F77_NO_MINUS_C_MINUS_O
@cvindex FC_NO_MINUS_C_MINUS_O
@caindex prog_f77_c_o
@caindex prog_fc_c_o
Test whether the Fortran compiler accepts the options @option{-c} and
@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
@code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
The result of the test is cached in the @code{ac_cv_prog_f77_c_o} or
@code{ac_cv_prog_fc_c_o} variable, respectively.
@end defmac
The following macros check for Fortran compiler characteristics.
To check for characteristics not listed here, use
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
@code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
@defmac AC_F77_LIBRARY_LDFLAGS
@defmacx AC_FC_LIBRARY_LDFLAGS
@acindex{F77_LIBRARY_LDFLAGS}
@ovindex FLIBS
@acindex{FC_LIBRARY_LDFLAGS}
@ovindex FCLIBS
@caindex prog_f77_v
@caindex prog_fc_v
@caindex f77_libs
@caindex fc_libs
Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
@dfn{Fortran intrinsic and runtime libraries} that are required to
successfully link a Fortran program or shared library. The output
variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
should be included after @code{LIBS} when linking).
This macro is intended to be used in those situations when it is
necessary to mix, e.g., C++ and Fortran source code in a single
program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
automake, GNU Automake}).
For example, if object files from a C++ and Fortran compiler must be
linked together, then the C++ compiler/linker must be used for linking
(since special C++-ish things need to happen at link time like calling
global constructors, instantiating templates, enabling exception
support, etc.).
However, the Fortran intrinsic and runtime libraries must be linked in
as well, but the C++ compiler/linker doesn't know by default how to add
these Fortran 77 libraries. Hence, this macro was created to determine
these Fortran libraries.
The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
@code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
link C/C++ with Fortran; see below. Further, it is highly recommended
that you use @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers})
because the complex defines that the function wrapper macros create
may not work with C/C++ compiler drivers.
These macros internally compute the flag needed to verbose linking
output and cache it in @code{ac_cv_prog_f77_v} or @code{ac_cv_prog_fc_v}
variables, respectively. The computed linker flags are cached in
@code{ac_cv_f77_libs} or @code{ac_cv_fc_libs}, respectively.
@end defmac
@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
AC_MSG_FAILURE})
@defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
AC_MSG_FAILURE})
@acindex{F77_DUMMY_MAIN}
@cvindex F77_DUMMY_MAIN
@acindex{FC_DUMMY_MAIN}
@cvindex FC_DUMMY_MAIN
@caindex f77_dummy_main
@caindex fc_dummy_main
With many compilers, the Fortran libraries detected by
@code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
their own @code{main} entry function that initializes things like
Fortran I/O, and which then calls a user-provided entry function named
(say) @code{MAIN__} to run the user's program. The
@code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
this interaction.
When using Fortran for purely numerical functions (no I/O, etc.)@: often
one prefers to provide one's own @code{main} and skip the Fortran
library initializations. In this case, however, one may still need to
provide a dummy @code{MAIN__} routine in order to prevent linking errors
on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
detects whether any such routine is @emph{required} for linking, and
what its name is; the shell variable @code{F77_DUMMY_MAIN} or
@code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
was found, and @code{none} when no such dummy main is needed.
By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
@code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
@emph{if} it is required. @var{action-if-not-found} defaults to
exiting with an error.
In order to link with Fortran routines, the user's C/C++ program should
then include the following code to define the dummy main if it is
needed:
@example
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
#ifdef F77_DUMMY_MAIN
# ifdef __cplusplus
extern "C"
# endif
int F77_DUMMY_MAIN () @{ return 1; @}
#endif
@end example
(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
or @code{AC_FC_WRAPPERS}; there is generally no need to call it
explicitly unless one wants to change the default actions.
The result of this macro is cached in the @code{ac_cv_f77_dummy_main} or
@code{ac_cv_fc_dummy_main} variable, respectively.
@end defmac
@defmac AC_F77_MAIN
@defmacx AC_FC_MAIN
@acindex{F77_MAIN}
@cvindex F77_MAIN
@acindex{FC_MAIN}
@cvindex FC_MAIN
@caindex f77_main
@caindex fc_main
As discussed above, many Fortran libraries allow you to provide an entry
point called (say) @code{MAIN__} instead of the usual @code{main}, which
is then called by a @code{main} function in the Fortran libraries that
initializes things like Fortran I/O@. The
@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
@emph{possible} to utilize such an alternate main function, and defines
@code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
simply defined to @code{main}.)
Thus, when calling Fortran routines from C that perform things like I/O,
one should use this macro and declare the "main" function like so:
@example
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
#ifdef __cplusplus
extern "C"
#endif
int F77_MAIN (int argc, char *argv[]);
@end example
(Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
The result of this macro is cached in the @code{ac_cv_f77_main} or
@code{ac_cv_fc_main} variable, respectively.
@end defmac
@defmac AC_F77_WRAPPERS
@defmacx AC_FC_WRAPPERS
@acindex{F77_WRAPPERS}
@cvindex F77_FUNC
@cvindex F77_FUNC_
@acindex{FC_WRAPPERS}
@cvindex FC_FUNC
@cvindex FC_FUNC_
@caindex f77_mangling
@caindex fc_mangling
Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
@code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
mangle the names of C/C++ identifiers, and identifiers with underscores,
respectively, so that they match the name-mangling scheme used by the
Fortran compiler.
Fortran is case-insensitive, and in order to achieve this the Fortran
compiler converts all identifiers into a canonical case and format. To
call a Fortran subroutine from C or to write a C function that is
callable from Fortran, the C program must explicitly use identifiers in
the format expected by the Fortran compiler. In order to do this, one
simply wraps all C identifiers in one of the macros provided by
@code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
you have the following Fortran 77 subroutine:
@example
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
subroutine foobar (x, y)
double precision x, y
y = 3.14159 * x
return
end
@end example
You would then declare its prototype in C or C++ as:
@example
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
#define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
#ifdef __cplusplus
extern "C" /* prevent C++ name mangling */
#endif
void FOOBAR_F77 (double *x, double *y);
@end example
Note that we pass both the lowercase and uppercase versions of the
function name to @code{F77_FUNC} so that it can select the right one.
Note also that all parameters to Fortran 77 routines are passed as
pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, GNU
Automake}).
(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
Although Autoconf tries to be intelligent about detecting the
name-mangling scheme of the Fortran compiler, there may be Fortran
compilers that it doesn't support yet. In this case, the above code
generates a compile-time error, but some other behavior
(e.g., disabling Fortran-related features) can be induced by checking
whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
Now, to call that routine from a C program, we would do something like:
@example
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
@{
double x = 2.7183, y;
FOOBAR_F77 (&x, &y);
@}
@end example
If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
@code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
because some Fortran compilers mangle names differently if they contain
an underscore.
The name mangling scheme is encoded in the @code{ac_cv_f77_mangling} or
@code{ac_cv_fc_mangling} cache variable, respectively, and also used for
the @code{AC_F77_FUNC} and @code{AC_FC_FUNC} macros described below.
@end defmac
@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
@defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
@acindex{F77_FUNC}
@acindex{FC_FUNC}
Given an identifier @var{name}, set the shell variable @var{shellvar} to
hold the mangled version @var{name} according to the rules of the
Fortran linker (see also @code{AC_F77_WRAPPERS} or
@code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
supplied, the shell variable is simply @var{name}. The purpose of
this macro is to give the caller a way to access the name-mangling
information other than through the C preprocessor as above, for example,
to call Fortran routines from some language other than C/C++.
@end defmac
@defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@defmacx AC_FC_PP_SRCEXT (@var{ext}, @ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_SRCEXT}
@acindex{FC_PP_SRCEXT}
@caindex fc_srcext_@var{ext}
@caindex fc_pp_srcext_@var{ext}
By default, the @code{FC} macros perform their tests using a @file{.f}
extension for source-code files. Some compilers, however, only enable
newer language features for appropriately named files, e.g., Fortran 90
features only for @file{.f90} files, or preprocessing only with
@file{.F} files or maybe other upper-case extensions. On the other
hand, some other compilers expect all source files to end in @file{.f}
and require special flags to support other file name extensions. The
@code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros deal with these
issues.
The @code{AC_FC_SRCEXT} macro tries to get the @code{FC} compiler to
accept files ending with the extension @file{.@var{ext}} (i.e.,
@var{ext} does @emph{not} contain the dot). If any special compiler
flags are needed for this, it stores them in the output variable
@code{FCFLAGS_@var{ext}}. This extension and these flags are then used
for all subsequent @code{FC} tests (until @code{AC_FC_SRCEXT} or
@code{AC_FC_PP_SRCEXT} is called another time).
For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
@file{.f90} extension in future tests, and it would set the
@code{FCFLAGS_f90} output variable with any extra flags that are needed
to compile such files.
Similarly, the @code{AC_FC_PP_SRCEXT} macro tries to get the @code{FC}
compiler to preprocess and compile files with the extension
@file{.@var{ext}}. When both @command{fpp} and @command{cpp} style
preprocessing are provided, the former is preferred, as the latter may
treat continuation lines, @code{//} tokens, and white space differently
from what some Fortran dialects expect. Conversely, if you do not want
files to be preprocessed, use only lower-case characters in the file
name extension. Like with @code{AC_FC_SRCEXT(f90)}, any needed flags
are stored in the @code{FCFLAGS_@var{ext}} variable.
The @code{FCFLAGS_@var{ext}} flags can @emph{not} be simply absorbed
into @code{FCFLAGS}, for two reasons based on the limitations of some
compilers. First, only one @code{FCFLAGS_@var{ext}} can be used at a
time, so files with different extensions must be compiled separately.
Second, @code{FCFLAGS_@var{ext}} must appear @emph{immediately} before
the source-code file name when compiling. So, continuing the example
above, you might compile a @file{foo.f90} file in your makefile with the
command:
@example
foo.o: foo.f90
$(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
@end example
If @code{AC_FC_SRCEXT} or @code{AC_FC_PP_SRCEXT} succeeds in compiling
files with the @var{ext} extension, it calls @var{action-if-success}
(defaults to nothing). If it fails, and cannot find a way to make the
@code{FC} compiler accept such files, it calls @var{action-if-failure}
(defaults to exiting with an error message).
The @code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros cache their
results in @code{ac_cv_fc_srcext_@var{ext}} and
@code{ac_cv_fc_pp_srcext_@var{ext}} variables, respectively.
@end defmac
@defmac AC_FC_PP_DEFINE (@ovar{action-if-success}, @dvar{action-if-failure, @
AC_MSG_FAILURE})
@acindex{FC_PP_DEFINE}
@caindex fc_pp_define
Find a flag to specify defines for preprocessed Fortran. Not all
Fortran compilers use @option{-D}. Substitute @code{FC_DEFINE} with
the result and call @var{action-if-success} (defaults to nothing) if
successful, and @var{action-if-failure} (defaults to failing with an
error message) if not.
This macro calls @code{AC_FC_PP_SRCEXT([F])} in order to learn how to
preprocess a @file{conftest.F} file, but restores a previously used
Fortran source file extension afterwards again.
The result of this test is cached in the @code{ac_cv_fc_pp_define}
variable.
@end defmac
@defmac AC_FC_FREEFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
AC_MSG_FAILURE})
@acindex{FC_FREEFORM}
@caindex fc_freeform
Try to ensure that the Fortran compiler (@code{$FC}) allows free-format
source code (as opposed to the older fixed-format style from Fortran
77). If necessary, it may add some additional flags to @code{FCFLAGS}.
This macro is most important if you are using the default @file{.f}
extension, since many compilers interpret this extension as indicating
fixed-format source unless an additional flag is supplied. If you
specify a different extension with @code{AC_FC_SRCEXT}, such as
@file{.f90}, then @code{AC_FC_FREEFORM} ordinarily succeeds without
modifying @code{FCFLAGS}. For extensions which the compiler does not
know about, the flag set by the @code{AC_FC_SRCEXT} macro might let
the compiler assume Fortran 77 by default, however.
If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
calls @var{action-if-success} (defaults to nothing). If it fails, it
calls @var{action-if-failure} (defaults to exiting with an error
message).
The result of this test, or @samp{none} or @samp{unknown}, is cached in
the @code{ac_cv_fc_freeform} variable.
@end defmac
@defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
AC_MSG_FAILURE})
@acindex{FC_FIXEDFORM}
@caindex fc_fixedform
Try to ensure that the Fortran compiler (@code{$FC}) allows the old
fixed-format source code (as opposed to free-format style). If
necessary, it may add some additional flags to @code{FCFLAGS}.
This macro is needed for some compilers alias names like @command{xlf95}
which assume free-form source code by default, and in case you want to
use fixed-form source with an extension like @file{.f90} which many
compilers interpret as free-form by default. If you specify a different
extension with @code{AC_FC_SRCEXT}, such as @file{.f}, then
@code{AC_FC_FIXEDFORM} ordinarily succeeds without modifying
@code{FCFLAGS}.
If @code{AC_FC_FIXEDFORM} succeeds in compiling fixed-form source, it
calls @var{action-if-success} (defaults to nothing). If it fails, it
calls @var{action-if-failure} (defaults to exiting with an error
message).
The result of this test, or @samp{none} or @samp{unknown}, is cached in
the @code{ac_cv_fc_fixedform} variable.
@end defmac
@defmac AC_FC_LINE_LENGTH (@ovar{length}, @ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_LINE_LENGTH}
@caindex fc_line_length
Try to ensure that the Fortran compiler (@code{$FC}) accepts long source
code lines. The @var{length} argument may be given as 80, 132, or
unlimited, and defaults to 132. Note that line lengths above 254
columns are not portable, and some compilers do not accept more than 132
columns at least for fixed format source. If necessary, it may add some
additional flags to @code{FCFLAGS}.
If @code{AC_FC_LINE_LENGTH} succeeds in compiling fixed-form source, it
calls @var{action-if-success} (defaults to nothing). If it fails, it
calls @var{action-if-failure} (defaults to exiting with an error
message).
The result of this test, or @samp{none} or @samp{unknown}, is cached in
the @code{ac_cv_fc_line_length} variable.
@end defmac
@defmac AC_FC_CHECK_BOUNDS (@ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_CHECK_BOUNDS}
@caindex fc_check_bounds
The @code{AC_FC_CHECK_BOUNDS} macro tries to enable array bounds checking
in the Fortran compiler. If successful, the @var{action-if-success}
is called and any needed flags are added to @code{FCFLAGS}. Otherwise,
@var{action-if-failure} is called, which defaults to failing with an error
message. The macro currently requires Fortran 90 or a newer dialect.
The result of the macro is cached in the @code{ac_cv_fc_check_bounds}
variable.
@end defmac
@defmac AC_F77_IMPLICIT_NONE (@ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@defmacx AC_FC_IMPLICIT_NONE (@ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{F77_IMPLICIT_NONE}
@acindex{FC_IMPLICIT_NONE}
@caindex f77_implicit_none
@caindex fc_implicit_none
Try to disallow implicit declarations in the Fortran compiler. If
successful, @var{action-if-success} is called and any needed flags
are added to @code{FFLAGS} or @code{FCFLAGS}, respectively. Otherwise,
@var{action-if-failure} is called, which defaults to failing with an error
message.
The result of these macros are cached in the
@code{ac_cv_f77_implicit_none} and @code{ac_cv_fc_implicit_none}
variables, respectively.
@end defmac
@defmac AC_FC_MODULE_EXTENSION
@acindex{FC_MODULE_EXTENSION}
@caindex fc_module_ext
@ovindex FC_MODEXT
Find the Fortran 90 module file name extension. Most Fortran 90
compilers store module information in files separate from the object
files. The module files are usually named after the name of the module
rather than the source file name, with characters possibly turned to
upper case, plus an extension, often @file{.mod}.
Not all compilers use module files at all, or by default. The Cray
Fortran compiler requires @option{-e m} in order to store and search
module information in @file{.mod} files rather than in object files.
Likewise, the Fujitsu Fortran compilers uses the @option{-Am} option to
indicate how module information is stored.
The @code{AC_FC_MODULE_EXTENSION} macro computes the module extension
without the leading dot, and stores that in the @code{FC_MODEXT}
variable. If the compiler does not produce module files, or the
extension cannot be determined, @code{FC_MODEXT} is empty. Typically,
the result of this macro may be used in cleanup @command{make} rules as
follows:
@example
clean-modules:
-test -z "$(FC_MODEXT)" || rm -f *.$(FC_MODEXT)
@end example
The extension, or @samp{unknown}, is cached in the
@code{ac_cv_fc_module_ext} variable.
@end defmac
@defmac AC_FC_MODULE_FLAG (@ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_MODULE_FLAG}
@caindex fc_module_flag
@ovindex FC_MODINC
@ovindex ac_empty
Find the compiler flag to include Fortran 90 module information from
another directory, and store that in the @code{FC_MODINC} variable.
Call @var{action-if-success} (defaults to nothing) if successful, and
set @code{FC_MODINC} to empty and call @var{action-if-failure} (defaults
to exiting with an error message) if not.
Most Fortran 90 compilers provide a way to specify module directories.
Some have separate flags for the directory to write module files to,
and directories to search them in, whereas others only allow writing to
the current directory or to the first directory specified in the include
path. Further, with some compilers, the module search path and the
preprocessor search path can only be modified with the same flag. Thus,
for portability, write module files to the current directory only and
list that as first directory in the search path.
There may be no whitespace between @code{FC_MODINC} and the following
directory name, but @code{FC_MODINC} may contain trailing white space.
For example, if you use Automake and would like to search @file{../lib}
for module files, you can use the following:
@example
AM_FCFLAGS = $(FC_MODINC). $(FC_MODINC)../lib
@end example
Inside @command{configure} tests, you can use:
@example
if test -n "$FC_MODINC"; then
FCFLAGS="$FCFLAGS $FC_MODINC. $FC_MODINC../lib"
fi
@end example
The flag is cached in the @code{ac_cv_fc_module_flag} variable.
The substituted value of @code{FC_MODINC} may refer to the
@code{ac_empty} dummy placeholder empty variable, to avoid losing
the significant trailing whitespace in a @file{Makefile}.
@end defmac
@defmac AC_FC_MODULE_OUTPUT_FLAG (@ovar{action-if-success}, @
@dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_MODULE_OUTPUT_FLAG}
@caindex fc_module_output_flag
@ovindex FC_MODOUT
Find the compiler flag to write Fortran 90 module information to
another directory, and store that in the @code{FC_MODOUT} variable.
Call @var{action-if-success} (defaults to nothing) if successful, and
set @code{FC_MODOUT} to empty and call @var{action-if-failure} (defaults
to exiting with an error message) if not.
Not all Fortran 90 compilers write module files, and of those that do,
not all allow writing to a directory other than the current one, nor
do all have separate flags for writing and reading; see the description
of @code{AC_FC_MODULE_FLAG} above. If you need to be able to write to
another directory, for maximum portability use @code{FC_MODOUT} before
any @code{FC_MODINC} and include both the current directory and the one
you write to in the search path:
@example
AM_FCFLAGS = $(FC_MODOUT)../mod $(FC_MODINC)../mod $(FC_MODINC). @dots{}
@end example
The flag is cached in the @code{ac_cv_fc_module_output_flag} variable.
The substituted value of @code{FC_MODOUT} may refer to the
@code{ac_empty} dummy placeholder empty variable, to avoid losing
the significant trailing whitespace in a @file{Makefile}.
@end defmac
@node Go Compiler
@subsection Go Compiler Characteristics
@cindex Go
Autoconf provides basic support for the Go programming language when
using the @code{gccgo} compiler (there is currently no support for the
@code{6g} and @code{8g} compilers).
@defmac AC_PROG_GO (@ovar{compiler-search-list})
Find the Go compiler to use. Check whether the environment variable
@code{GOC} is set; if so, then set output variable @code{GOC} to its
value.
Otherwise, if the macro is invoked without an argument, then search for
a Go compiler named @code{gccgo}. If it is not found, then as a last
resort set @code{GOC} to @code{gccgo}.
This macro may be invoked with an optional first argument which, if
specified, must be a blank-separated list of Go compilers to search for.
If output variable @code{GOFLAGS} was not already set, set it to
@option{-g -O2}. If your package does not like this default,
@code{GOFLAGS} may be set before @code{AC_PROG_GO}.
@end defmac
@node System Services
@section System Services
The following macros check for operating system services or capabilities.
@anchor{AC_PATH_X}
@defmac AC_PATH_X
@acindex{PATH_X}
@evindex XMKMF
@cindex X Window System
Try to locate the X Window System include files and libraries. If the
user gave the command line options @option{--x-includes=@var{dir}} and
@option{--x-libraries=@var{dir}}, use those directories.
If either or both were not given, get the missing values by running
@code{xmkmf} (or an executable pointed to by the @code{XMKMF}
environment variable) on a trivial @file{Imakefile} and examining the
makefile that it produces. Setting @code{XMKMF} to @samp{false}
disables this method.
If this method fails to find the X Window System, @command{configure}
looks for the files 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
@option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
otherwise set it to the empty string.
@end defmac
@anchor{AC_PATH_XTRA}
@defmac AC_PATH_XTRA
@acindex{PATH_XTRA}
@ovindex X_CFLAGS
@ovindex X_LIBS
@ovindex X_EXTRA_LIBS
@ovindex X_PRE_LIBS
@cvindex X_DISPLAY_MISSING
An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
that X needs to output variable @code{X_CFLAGS}, and the X linker flags
to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
available.
This macro also checks for special libraries that some systems need in
order to compile X programs. It adds any that the system needs to
output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
libraries that need to be linked with before @option{-lX11}, and adds
any found to the output variable @code{X_PRE_LIBS}.
@c This is an incomplete kludge. Make a real way to do it.
@c If you need to check for other X functions or libraries yourself, then
@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
@c @code{LIBS} temporarily, like this: (FIXME - add example)
@end defmac
@anchor{AC_SYS_INTERPRETER}
@defmac AC_SYS_INTERPRETER
@acindex{SYS_INTERPRETER}
Check whether the system supports starting scripts with a line of the
form @samp{#!/bin/sh} to select the interpreter to use for the script.
After running this macro, shell code in @file{configure.ac} can check
the shell variable @code{interpval}; it is set to @samp{yes}
if the system supports @samp{#!}, @samp{no} if not.
@end defmac
@defmac AC_SYS_LARGEFILE
@acindex{SYS_LARGEFILE}
@cvindex _FILE_OFFSET_BITS
@cvindex _LARGE_FILES
@ovindex CC
@cindex Large file support
@cindex LFS
Arrange for 64-bit file offsets, known as
@uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html,
large-file support}. On some hosts, one must use special compiler
options to build programs that can access large files. Append any such
options to the output variable @code{CC}. Define
@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
Large-file support can be disabled by configuring with the
@option{--disable-largefile} option.
If you use this macro, check that your program works even when
@code{off_t} is wider than @code{long int}, since this is common when
large-file support is enabled. For example, it is not correct to print
an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
(long int) X)}.
The LFS introduced the @code{fseeko} and @code{ftello} functions to
replace their C counterparts @code{fseek} and @code{ftell} that do not
use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
prototypes available when using them and large-file support is
enabled.
@end defmac
@anchor{AC_SYS_LONG_FILE_NAMES}
@defmac AC_SYS_LONG_FILE_NAMES
@acindex{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_POSIX_TERMIOS
@acindex{SYS_POSIX_TERMIOS}
@cindex Posix termios headers
@cindex termios Posix headers
@caindex sys_posix_termios
Check to see if the Posix termios headers and functions are available on the
system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
@samp{yes}. If not, set the variable to @samp{no}.
@end defmac
@node Posix Variants
@section Posix Variants
The following macro makes it possible to use features of Posix that are
extensions to C, as well as platform extensions not defined by Posix.
@anchor{AC_USE_SYSTEM_EXTENSIONS}
@defmac AC_USE_SYSTEM_EXTENSIONS
@acindex{USE_SYSTEM_EXTENSIONS}
@cvindex _ALL_SOURCE
@cvindex _GNU_SOURCE
@cvindex _MINIX
@cvindex _POSIX_1_SOURCE
@cvindex _POSIX_PTHREAD_SEMANTICS
@cvindex _POSIX_SOURCE
@cvindex _TANDEM_SOURCE
@cvindex __EXTENSIONS__
This macro was introduced in Autoconf 2.60. If possible, enable
extensions to C or Posix on hosts that normally disable the extensions,
typically due to standards-conformance namespace issues. This should be
called before any macros that run the C compiler. The following
preprocessor macros are defined where appropriate:
@table @code
@item _GNU_SOURCE
Enable extensions on GNU/Linux.
@item __EXTENSIONS__
Enable general extensions on Solaris.
@item _POSIX_PTHREAD_SEMANTICS
Enable threading extensions on Solaris.
@item _TANDEM_SOURCE
Enable extensions for the HP NonStop platform.
@item _ALL_SOURCE
Enable extensions for AIX 3, and for Interix.
@item _POSIX_SOURCE
Enable Posix functions for Minix.
@item _POSIX_1_SOURCE
Enable additional Posix functions for Minix.
@item _MINIX
Identify Minix platform. This particular preprocessor macro is
obsolescent, and may be removed in a future release of Autoconf.
@end table
@end defmac
@node Erlang Libraries
@section Erlang Libraries
@cindex Erlang, Library, checking
The following macros check for an installation of Erlang/OTP, and for the
presence of certain Erlang libraries. All those macros require the
configuration of an Erlang interpreter and an Erlang compiler
(@pxref{Erlang Compiler and Interpreter}).
@defmac AC_ERLANG_SUBST_ERTS_VER
@acindex{ERLANG_SUBST_ERTS_VER}
@ovindex ERLANG_ERTS_VER
Set the output variable @code{ERLANG_ERTS_VER} to the version of the
Erlang runtime system (as returned by Erlang's
@code{erlang:system_info(version)} function). The result of this test
is cached if caching is enabled when running @command{configure}. The
@code{ERLANG_ERTS_VER} variable is not intended to be used for testing
for features of specific ERTS versions, but to be used for substituting
the ERTS version in Erlang/OTP release resource files (@code{.rel}
files), as shown below.
@end defmac
@defmac AC_ERLANG_SUBST_ROOT_DIR
@acindex{ERLANG_SUBST_ROOT_DIR}
@ovindex ERLANG_ROOT_DIR
Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base
directory in which Erlang/OTP is installed (as returned by Erlang's
@code{code:root_dir/0} function). The result of this test is cached if
caching is enabled when running @command{configure}.
@end defmac
@defmac AC_ERLANG_SUBST_LIB_DIR
@acindex{ERLANG_SUBST_LIB_DIR}
@ovindex ERLANG_LIB_DIR
Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
directory of Erlang/OTP (as returned by Erlang's
@code{code:lib_dir/0} function), which subdirectories each contain an installed
Erlang/OTP library. The result of this test is cached if caching is enabled
when running @command{configure}.
@end defmac
@defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @
@ovar{action-if-not-found})
@acindex{ERLANG_CHECK_LIB}
@ovindex ERLANG_LIB_DIR_@var{library}
@ovindex ERLANG_LIB_VER_@var{library}
Test whether the Erlang/OTP library @var{library} is installed by
calling Erlang's @code{code:lib_dir/1} function. The result of this
test is cached if caching is enabled when running @command{configure}.
@var{action-if-found} is a list of shell commands to run if the library
is installed; @var{action-if-not-found} is a list of shell commands to
run if it is not. Additionally, if the library is installed, the output
variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
library installation directory, and the output variable
@samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
part of the subdirectory name, if it is in the standard form
(@code{@var{library}-@var{version}}). If the directory name does not
have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
empty string. If the library is not installed,
@samp{ERLANG_LIB_DIR_@var{library}} and
@samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
example, to check if library @code{stdlib} is installed:
@example
AC_ERLANG_CHECK_LIB([stdlib],
[echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
[AC_MSG_ERROR([stdlib was not found!])])
@end example
The @samp{ERLANG_LIB_VER_@var{library}} variables (set by
@code{AC_ERLANG_CHECK_LIB}) and the @code{ERLANG_ERTS_VER} variable (set
by @code{AC_ERLANG_SUBST_ERTS_VER}) are not intended to be used for
testing for features of specific versions of libraries or of the Erlang
runtime system. Those variables are intended to be substituted in
Erlang release resource files (@code{.rel} files). For instance, to
generate a @file{example.rel} file for an application depending on the
@code{stdlib} library, @file{configure.ac} could contain:
@example
AC_ERLANG_SUBST_ERTS_VER
AC_ERLANG_CHECK_LIB([stdlib],
[],
[AC_MSG_ERROR([stdlib was not found!])])
AC_CONFIG_FILES([example.rel])
@end example
@noindent
The @file{example.rel.in} file used to generate @file{example.rel}
should contain:
@example
@{release,
@{"@@PACKAGE@@", "@@VERSION@@"@},
@{erts, "@@ERLANG_ERTS_VER@@"@},
[@{stdlib, "@@ERLANG_LIB_VER_stdlib@@"@},
@{@@PACKAGE@@, "@@VERSION@@"@}]@}.
@end example
@end defmac
In addition to the above macros, which test installed Erlang libraries, the
following macros determine the paths to the directories into which newly built
Erlang libraries are to be installed:
@defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
@acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
@ovindex ERLANG_INSTALL_LIB_DIR
Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
which every built Erlang library should be installed in a separate
subdirectory.
If this variable is not set in the environment when @command{configure} runs,
its default value is @code{$@{libdir@}/erlang/lib}.
@end defmac
@defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
@ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
directory into which the built Erlang library @var{library} version
@var{version} should be installed. If this variable is not set in the
environment when @command{configure} runs, its default value is
@samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
@code{ERLANG_INSTALL_LIB_DIR} variable being set by the
@code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
@end defmac
@c ========================================================= Writing Tests
@node Writing Tests
@chapter Writing Tests
If the existing feature tests don't do something you need, you have to
write new ones. These macros are the building blocks. They provide
ways for other macros to check whether various kinds of features are
available and report the results.
This chapter contains some suggestions and some of the reasons why the
existing tests are written the way they are. You can also learn a lot
about how to write Autoconf tests by looking at the existing ones. If
something goes wrong in one or more of the Autoconf tests, this
information can help you understand the assumptions behind them, which
might help you figure out how to best solve the problem.
These macros check the output of the compiler system of the current
language (@pxref{Language Choice}). They do not cache the results of
their tests for future use (@pxref{Caching Results}), because they don't
know enough about the information they are checking for to generate a
cache variable name. They also do not print any messages, for the same
reason. The checks for particular kinds of features call these macros
and do cache their results and print messages about what they're
checking for.
When you write a feature test that could be applicable to more than one
software package, the best thing to do is encapsulate it in a new macro.
@xref{Writing Autoconf Macros}, for how to do that.
@menu
* Language Choice:: Selecting which language to use for testing
* Writing Test Programs:: Forging source files for compilers
* Running the Preprocessor:: Detecting preprocessor symbols
* Running the Compiler:: Detecting language or header features
* Running the Linker:: Detecting library features
* Runtime:: Testing for runtime features
* Systemology:: A zoology of operating systems
* Multiple Cases:: Tests for several possible values
@end menu
@node Language Choice
@section Language Choice
@cindex Language
Autoconf-generated @command{configure} scripts check for the C compiler and
its features by default. Packages that use other programming languages
(maybe more than one, e.g., C and C++) need to test features of the
compilers for the respective languages. The following macros determine
which programming language is used in the subsequent tests in
@file{configure.ac}.
@anchor{AC_LANG}
@defmac AC_LANG (@var{language})
@acindex{LANG}
Do compilation tests using the compiler, preprocessor, and file
extensions for the specified @var{language}.
Supported languages are:
@table @samp
@item C
Do compilation tests using @code{CC} and @code{CPP} and use extension
@file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
@code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
@item C++
Do compilation tests using @code{CXX} and @code{CXXCPP} and use
extension @file{.C} for test programs. Use compilation flags:
@code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
@code{CXXFLAGS} with @code{CXX}.
@item Fortran 77
Do compilation tests using @code{F77} and use extension @file{.f} for
test programs. Use compilation flags: @code{FFLAGS}.
@item Fortran
Do compilation tests using @code{FC} and use extension @file{.f} (or
whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
compilation flags: @code{FCFLAGS}.
@item Erlang
@ovindex ERLC
@ovindex ERL
@ovindex ERLCFLAGS
Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
@file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
@item Objective C
Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
extension @file{.m} for test programs. Use compilation flags:
@code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
@code{OBJCFLAGS} with @code{OBJC}.
@item Objective C++
Do compilation tests using @code{OBJCXX} and @code{OBJCXXCPP} and use
extension @file{.mm} for test programs. Use compilation flags:
@code{CPPFLAGS} with @code{OBJCXXCPP}, and both @code{CPPFLAGS} and
@code{OBJCXXFLAGS} with @code{OBJCXX}.
@item Go
Do compilation tests using @code{GOC} and use extension @file{.go} for
test programs. Use compilation flags @code{GOFLAGS}.
@end table
@end defmac
@anchor{AC_LANG_PUSH}
@defmac AC_LANG_PUSH (@var{language})
@acindex{LANG_PUSH}
Remember the current language (as set by @code{AC_LANG}) on a stack, and
then select the @var{language}. Use this macro and @code{AC_LANG_POP}
in macros that need to temporarily switch to a particular language.
@end defmac
@defmac AC_LANG_POP (@ovar{language})
@acindex{LANG_POP}
Select the language that is saved on the top of the stack, as set by
@code{AC_LANG_PUSH}, and remove it from the stack.
If given, @var{language} specifies the language we just @emph{quit}. It
is a good idea to specify it when it's known (which should be the
case@dots{}), since Autoconf detects inconsistencies.
@example
AC_LANG_PUSH([Fortran 77])
# Perform some tests on Fortran 77.
# @dots{}
AC_LANG_POP([Fortran 77])
@end example
@end defmac
@defmac AC_LANG_ASSERT (@var{language})
@acindex{LANG_ASSERT}
Check statically that the current language is @var{language}.
You should use this in your language specific macros
to avoid that they be called with an inappropriate language.
This macro runs only at @command{autoconf} time, and incurs no cost at
@command{configure} time. Sadly enough and because Autoconf is a two
layer language @footnote{Because M4 is not aware of Sh code,
especially conditionals, some optimizations that look nice statically
may produce incorrect results at runtime.}, the macros
@code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
therefore as much as possible you ought to avoid using them to wrap
your code, rather, require from the user to run the macro with a
correct current language, and check it with @code{AC_LANG_ASSERT}.
And anyway, that may help the user understand she is running a Fortran
macro while expecting a result about her Fortran 77 compiler@enddots{}
@end defmac
@defmac AC_REQUIRE_CPP
@acindex{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 Test Programs
@section Writing Test Programs
Autoconf tests follow a common scheme: feed some program with some
input, and most of the time, feed a compiler with some source file.
This section is dedicated to these source samples.
@menu
* Guidelines:: General rules for writing test programs
* Test Functions:: Avoiding pitfalls in test programs
* Generating Sources:: Source program boilerplate
@end menu
@node Guidelines
@subsection Guidelines for Test Programs
The most important rule to follow when writing testing samples is:
@center @emph{Look for realism.}
This motto means that testing samples must be written with the same
strictness as real programs are written. In particular, you should
avoid ``shortcuts'' and simplifications.
Don't just play with the preprocessor if you want to prepare a
compilation. For instance, using @command{cpp} to check whether a header is
functional might let your @command{configure} accept a header which
causes some @emph{compiler} error. Do not hesitate to check a header with
other headers included before, especially required headers.
Make sure the symbols you use are properly defined, i.e., refrain from
simply declaring a function yourself instead of including the proper
header.
Test programs should not write to standard output. They
should exit with status 0 if the test succeeds, and with status 1
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. Unless you arrange for @code{exit} to be declared, test
programs should @code{return}, not @code{exit}, from @code{main},
because on many systems @code{exit} is not declared by default.
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_STDBOOL}, then later on in
@file{configure.ac} you can have a test program that includes
@file{stdbool.h} conditionally:
@example
@group
#ifdef HAVE_STDBOOL_H
# include <stdbool.h>
#endif
@end group
@end example
Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
work with any standard C compiler. Some developers prefer @code{#if}
because it is easier to read, while others prefer @code{#ifdef} because
it avoids diagnostics with picky compilers like GCC with the
@option{-Wundef} option.
If a test program needs to use or create a data file, give it a name
that starts with @file{conftest}, such as @file{conftest.data}. The
@command{configure} script cleans up by running @samp{rm -f -r conftest*}
after running test programs and if the script is interrupted.
@node Test Functions
@subsection Test Functions
These days it's safe to assume support for function prototypes
(introduced in C89).
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"
#endif
void *valloc (size_t);
@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, be 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 Generating Sources
@subsection Generating Sources
Autoconf provides a set of macros that can be used to generate test
source files. They are written to be language generic, i.e., they
actually depend on the current language (@pxref{Language Choice}) to
``format'' the output properly.
@defmac AC_LANG_CONFTEST (@var{source})
@acindex{LANG_CONFTEST}
Save the @var{source} text in the current test source file:
@file{conftest.@var{extension}} where the @var{extension} depends on the
current language. As of Autoconf 2.63b, the source file also contains
the results of all of the @code{AC_DEFINE} performed so far.
Note that the @var{source} is evaluated exactly once, like regular
Autoconf macro arguments, and therefore (i) you may pass a macro
invocation, (ii) if not, be sure to double quote if needed.
This macro issues a warning during @command{autoconf} processing if
@var{source} does not include an expansion of the macro
@code{AC_LANG_DEFINES_PROVIDED} (note that both @code{AC_LANG_SOURCE} and
@code{AC_LANG_PROGRAM} call this macro, and thus avoid the warning).
This macro is seldom called directly, but is used under the hood by more
common macros such as @code{AC_COMPILE_IFELSE} and @code{AC_RUN_IFELSE}.
@end defmac
@defmac AC_LANG_DEFINES_PROVIDED
@acindex{LANG_DEFINES_PROVIDED}
This macro is called as a witness that the file
@file{conftest.@var{extension}} appropriate for the current language is
complete, including all previously determined results from
@code{AC_DEFINE}. This macro is seldom called directly, but exists if
you have a compelling reason to write a conftest file without using
@code{AC_LANG_SOURCE}, yet still want to avoid a syntax warning from
@code{AC_LANG_CONFTEST}.
@end defmac
@defmac AC_LANG_SOURCE (@var{source})
@acindex{LANG_SOURCE}
Expands into the @var{source}, with the definition of
all the @code{AC_DEFINE} performed so far. This macro includes an
expansion of @code{AC_LANG_DEFINES_PROVIDED}.
In many cases, you may find it more convenient to use the wrapper
@code{AC_LANG_PROGRAM}.
@end defmac
For instance, executing (observe the double quotation!):
@example
@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
[
http://www.example.org/])
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
[Greetings string.])
AC_LANG([C])
AC_LANG_CONFTEST(
[AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
gcc -E -dD conftest.c
@end example
@noindent
on a system with @command{gcc} installed, results in:
@example
@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
@dots{}
# 1 "conftest.c"
#define PACKAGE_NAME "Hello"
#define PACKAGE_TARNAME "hello"
#define PACKAGE_VERSION "1.0"
#define PACKAGE_STRING "Hello 1.0"
#define PACKAGE_BUGREPORT "bug-hello@@example.org"
#define PACKAGE_URL "
http://www.example.org/"
#define HELLO_WORLD "Hello, World\n"
const char hw[] = "Hello, World\n";
@end example
When the test language is Fortran, Erlang, or Go, the @code{AC_DEFINE}
definitions are not automatically translated into constants in the
source code by this macro.
@defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
@acindex{LANG_PROGRAM}
Expands into a source file which consists of the @var{prologue}, and
then @var{body} as body of the main function (e.g., @code{main} in
C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
available.
@end defmac
For instance:
@example
@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
[
http://www.example.org/])
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
[Greetings string.])
AC_LANG_CONFTEST(
[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
[[fputs (hw, stdout);]])])
gcc -E -dD conftest.c
@end example
@noindent
on a system with @command{gcc} installed, results in:
@example
@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
@dots{}
# 1 "conftest.c"
#define PACKAGE_NAME "Hello"
#define PACKAGE_TARNAME "hello"
#define PACKAGE_VERSION "1.0"
#define PACKAGE_STRING "Hello 1.0"
#define PACKAGE_BUGREPORT "bug-hello@@example.org"
#define PACKAGE_URL "
http://www.example.org/"
#define HELLO_WORLD "Hello, World\n"
const char hw[] = "Hello, World\n";
int
main ()
@{
fputs (hw, stdout);
;
return 0;
@}
@end example
In Erlang tests, the created source file is that of an Erlang module called
@code{conftest} (@file{conftest.erl}). This module defines and exports
at least
one @code{start/0} function, which is called to perform the test. The
@var{prologue} is optional code that is inserted between the module header and
the @code{start/0} function definition. @var{body} is the body of the
@code{start/0} function without the final period (@pxref{Runtime}, about
constraints on this function's behavior).
For instance:
@example
AC_INIT([Hello], [1.0], [bug-hello@@example.org])
AC_LANG(Erlang)
AC_LANG_CONFTEST(
[AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
[[io:format("~s~n", [?HELLO_WORLD])]])])
cat conftest.erl
@end example
@noindent
results in:
@example
-module(conftest).
-export([start/0]).
-define(HELLO_WORLD, "Hello, world!").
start() ->
io:format("~s~n", [?HELLO_WORLD])
