Linux From Scratch .info files

This is autoconf.info, produced by makeinfo version 4.6 from
autoconf.texi.

This manual is for GNU Autoconf (version 2.59, 5 November 2003), a
package for creating scripts to configure source code packages using
templates and an M4 macro package.

Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual," and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License."

(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by
the Free Software Foundation raise funds for GNU development."

INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* Autoconf: (autoconf). Create source code configuration scripts.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* autoscan: (autoconf)autoscan Invocation.
Semi-automatic `configure.ac' writing
* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
* autoconf: (autoconf)autoconf Invocation.
How to create configuration scripts
* autoreconf: (autoconf)autoreconf Invocation.
Remaking multiple `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 `configure.ac'
* config.status: (autoconf)config.status Invocation. Recreating configurations.
* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
END-INFO-DIR-ENTRY

File: autoconf.info, Node: Top, Next: Introduction, Up: (dir)

Autoconf
********

This manual is for GNU Autoconf (version 2.59, 5 November 2003), a
package for creating scripts to configure source code packages using
templates and an M4 macro package.

(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by
the Free Software Foundation raise funds for GNU development."

* 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
* Writing Autoconf Macros:: Adding new macros to Autoconf
* Portable Shell:: Shell script portability pitfalls
* Manual Configuration:: Selecting features that can't be guessed
* Site Configuration:: Local defaults for `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
* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of symbols, concepts, etc.

--- The Detailed Node Listing ---

The GNU Build System

* Automake:: Escaping Makefile hell
* Libtool:: Building libraries portably
* Pointers:: More info on the GNU build system

Making `configure' Scripts

* Writing configure.ac:: What to put in an Autoconf input file
* autoscan Invocation:: Semi-automatic `configure.ac' writing
* ifnames Invocation:: Listing the conditionals in source code
* autoconf Invocation:: How to create configuration scripts
* autoreconf Invocation:: Remaking multiple `configure' scripts

Writing `configure.ac'

* Shell Script Compiler:: Autoconf as solution of a problem
* Autoconf Language:: Programming in Autoconf
* configure.ac Layout:: Standard organization of `configure.ac'

Initialization and Output Files

* Initializing configure:: Option processing etc.
* Notices:: Copyright, version numbers in `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 `Makefile's
* 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
* 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
* UNIX Variants:: Special kludges for specific UNIX variants

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
* Fortran 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
* Run Time:: Testing for run-time 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
* Caching Results:: Speeding up subsequent `configure' runs
* Printing Messages:: Notifying `configure' users

Caching Results

* Cache Variable Names:: Shell variables used in caches
* Cache Files:: Files `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
* Programming in M4sh:: Common shell Constructs

M4 Quotation

* Active Characters:: Characters that change the behavior of M4
* One Macro Call:: Quotation and one macro call
* Quotation and Nested Macros:: Macros calling macros
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
* Quadrigraphs:: Another way to escape special characters
* Quotation Rule Of Thumb:: One parenthesis, one quote

Using `autom4te'

* autom4te Invocation:: A GNU M4 wrapper
* Customizing autom4te:: Customizing the Autoconf package

Programming in M4sugar

* Redefined M4 Macros:: M4 builtins changed in M4sugar
* Evaluation Macros:: More quotation and evaluation control
* Forbidden Patterns:: Catching unexpanded macros

Writing Autoconf Macros

* Macro Definitions:: Basic format of an Autoconf macro
* Macro Names:: What to call your new macros
* Reporting Messages:: Notifying `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

Portable Shell Programming

* Shellology:: A zoology of shells
* Here-Documents:: Quirks and tricks
* File Descriptors:: FDs and redirections
* File System Conventions:: File- and pathnames
* Shell Substitutions:: Variable and command expansions
* Assignments:: Varying side effects of assignments
* Parentheses:: Parentheses in shell scripts
* Special Shell Variables:: Variables you should not change
* Limitations of Builtins:: Portable use of not so portable /bin/sh
* Limitations of Usual Tools:: Portable use of portable tools
* Limitations of Make:: Portable Makefiles

Manual Configuration

* Specifying Names:: Specifying the system type
* Canonicalizing:: Getting the canonical system type
* Using System Type:: What to do with the system type

Site Configuration

* External Software:: Working with other optional software
* Package Options:: Selecting optional features
* Pretty Help Strings:: Formatting help string
* Site Details:: Configuring site details
* Transforming Names:: Changing program names when installing
* Site Defaults:: Giving `configure' local defaults

Transforming Program Names When Installing

* Transformation Options:: `configure' options to transform names
* Transformation Examples:: Sample uses of transforming names
* Transformation Rules:: `Makefile' uses of transforming names

Running `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
* System Type:: Specifying the system type
* Sharing Defaults:: Setting site-wide defaults for `configure'
* Defining Variables:: Specifying the compiler etc.
* configure Invocation:: Changing how `configure' runs

Obsolete Constructs

* Obsolete config.status Use:: Different calling convention
* acconfig.h:: Additional entries in `config.h.in'
* autoupdate Invocation:: Automatic update of `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 `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_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources

Generating Test Suites with Autotest

* Using an Autotest Test Suite:: Autotest and the user
* Writing testsuite.at:: Autotest macros
* testsuite Invocation:: Running `testsuite' scripts
* Making testsuite Scripts:: Using autom4te to create `testsuite'

Using an Autotest Test Suite

* testsuite Scripts:: The concepts of Autotest
* Autotest Logs:: Their contents

Frequent Autoconf Questions, with answers

* Distributing:: Distributing `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 `configure' instead of Imake
* Defining Directories:: Passing `datadir' to program
* autom4te.cache:: What is it? Can I remove it?
* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree

History of Autoconf

* Genesis:: Prehistory and naming of `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

Copying This Manual

* GNU Free Documentation License:: License for copying this manual

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
* 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

File: autoconf.info, Node: Introduction, Next: The GNU Build System, Prev: Top, Up: Top

Introduction
************

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..." "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..." The computer scientist
shouted: "And the Chaos, where do you think it was coming from, hmm?"

--Anonymous

Autoconf is a tool for producing shell scripts that automatically
configure software source code packages to adapt to many kinds of
UNIX-like systems. The configuration scripts produced by Autoconf are
independent of Autoconf when they are run, so their users do not need
to have Autoconf.

The configuration scripts produced by Autoconf require no manual user
intervention when run; they do not normally even need an argument
specifying the system type. Instead, they 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 UNIX variants.
There is no need to maintain files that list the features supported by
each release of each variant of UNIX.

For each software package that Autoconf is used with, it creates a
configuration script from a template file that lists the system features
that the package needs or can use. After the shell code to recognize
and respond to a system feature has been written, Autoconf allows it to
be shared by many software packages that can use (or need) that feature.
If it later turns out that the shell code needs adjustment for some
reason, it needs to be changed in only one place; all of the
configuration scripts can be regenerated automatically to take advantage
of the updated code.

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. *Note The GNU Build System::, for more
information.

Autoconf imposes some restrictions on the names of macros used with
`#if' in C programs (*note Preprocessor Symbol Index::).

Autoconf requires GNU M4 in order to generate the scripts. It uses
features that some UNIX versions of M4, including GNU M4 1.3, do not
have. You must use version 1.4 or later of GNU M4.

*Note Autoconf 1::, for information about upgrading from version 1.
*Note History::, for the story of Autoconf's development. *Note FAQ::,
for answers to some common questions about Autoconf.

See the Autoconf web page(1) for up-to-date information, details on
the mailing lists, pointers to a list of known bugs, etc.

Mail suggestions to the Autoconf mailing list <autoconf@gnu.org>.

Bug reports should be preferably submitted to the Autoconf Gnats
database(2), or sent to the Autoconf Bugs mailing list
<bug-autoconf@gnu.org>. 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 `configure.ac' that demonstrates the problem.

Autoconf's development tree is accessible via CVS; see the Autoconf
web page for details. There is also a CVSweb interface to the Autoconf
development tree(3). Patches relative to the current CVS version can
be sent for review to the Autoconf Patches mailing list
<autoconf-patches@gnu.org>.

Because of its mission, Autoconf 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
Autoconf Macro Archive(4), which is kindly run by Peter Simons
<simons@computer.org>.

---------- Footnotes ----------

(1) Autoconf web page,
<http://www.gnu.org/software/autoconf/autoconf.html>.

(2) Autoconf Gnats database,
<http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=autoconf>.

(3) CVSweb interface to the Autoconf development tree,
<http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/>.

(4) Autoconf Macro Archive,
<http://www.gnu.org/software/ac-archive/>.

File: autoconf.info, Node: The GNU Build System, Next: Making configure Scripts, Prev: Introduction, Up: Top

The GNU Build System
********************

Autoconf solves an important problem--reliable discovery of
system-specific build and run-time 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
* Libtool:: Building libraries portably
* Pointers:: More info on the GNU build system

File: autoconf.info, Node: Automake, Next: Libtool, Up: The GNU Build System

Automake
========

The ubiquity of `make' means that a `Makefile' is almost the only
viable way to distribute automatic build rules for software, but one
quickly runs into `make''s numerous limitations. Its lack of support
for automatic dependency tracking, recursive builds in subdirectories,
reliable timestamps (e.g., for network filesystems), 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 `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 (`make install', `make distclean', `make uninstall',
etc.). Since you are, of course, using Autoconf, you also have to
insert repetitive code in your `Makefile.in' to recognize `@CC@',
`@CFLAGS@', and other substitutions provided by `configure'. Into this
mess steps "Automake".

Automake allows you to specify your build needs in a `Makefile.am'
file with a vastly simpler and more powerful syntax than that of a plain
`Makefile', and then generates a portable `Makefile.in' for use with
Autoconf. For example, the `Makefile.am' to build and install a simple
"Hello world" program might look like:

bin_PROGRAMS = hello
hello_SOURCES = hello.c

The resulting `Makefile.in' (~400 lines) automatically supports all the
standard targets, the substitutions provided by Autoconf, automatic
dependency tracking, `VPATH' building, and so on. `make' will build
the `hello' program, and `make install' will install it in
`/usr/local/bin' (or whatever prefix was given to `configure', if not
`/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....

File: autoconf.info, Node: Libtool, Next: Pointers, Prev: Automake, Up: The GNU Build System

Libtool
=======

Very 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 _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:
"Libtool".

Libtool handles all the requirements of building shared libraries for
you, and at this time seems to be the _only_ way to do so with any
portability. It also handles many other headaches, such as: the
interaction of `Makefile' 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 on its own, 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.

File: autoconf.info, Node: Pointers, Prev: Libtool, Up: The GNU Build System

Pointers
========

Developers who are used to the simplicity of `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 will 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 will be a
piece of cake.)

There are a number of places that you can go to for more information
on the GNU build tools.

- Web

The home pages for Autoconf(1), Automake(2), and Libtool(3).

- Automake Manual

*Note Automake: (automake)Top, for more information on Automake.

- Books

The book `GNU Autoconf, Automake and Libtool'(4) describes the
complete GNU build environment. You can also find the entire book
on-line at "The Goat Book" home page(5).

- Tutorials and Examples

The Autoconf Developer Page(6) maintains links to a number of
Autoconf/Automake tutorials online, and also links to the Autoconf
Macro Archive(7).

---------- Footnotes ----------

(1) Autoconf, <http://www.gnu.org/software/autoconf/>.

(2) Automake, <http://www.gnu.org/software/automake/>.

(3) Libtool, <http://www.gnu.org/software/libtool/>.

(4) `GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B.
Elliston, T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN
1578701902.

(5) "The Goat Book" home page, <http://sources.redhat.com/autobook/>.

(6) Autoconf Developer Page, <http://sources.redhat.com/autoconf/>.

(7) Autoconf Macro Archive,
<http://www.gnu.org/software/ac-archive/>.

File: autoconf.info, Node: Making configure Scripts, Next: Setup, Prev: The GNU Build System, Up: Top

Making `configure' Scripts
**************************

The configuration scripts that Autoconf produces are by convention
called `configure'. When run, `configure' creates several files,
replacing configuration parameters in them with appropriate values.
The files that `configure' creates are:

- one or more `Makefile' files, usually one in each subdirectory of
the package (*note Makefile Substitutions::);

- optionally, a C header file, the name of which is configurable,
containing `#define' directives (*note Configuration Headers::);

- a shell script called `config.status' that, when run, will recreate
the files listed above (*note config.status Invocation::);

- an optional shell script normally called `config.cache' (created
when using `configure --config-cache') that saves the results of
running many of the tests (*note Cache Files::);

- a file called `config.log' containing any messages produced by
compilers, to help debugging if `configure' makes a mistake.

To create a `configure' script with Autoconf, you need to write an
Autoconf input file `configure.ac' (or `configure.in') and run
`autoconf' on it. If you write your own feature tests to supplement
those that come with Autoconf, you might also write files called
`aclocal.m4' and `acsite.m4'. If you use a C header file to contain
`#define' directives, you might also run `autoheader', and you will
distribute the generated 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
`*'. Optional files are enclosed in square brackets (`[]').
`autoconf' and `autoheader' also read the installed Autoconf macro
files (by reading `autoconf.m4').

Files used in preparing a software package for distribution:
your source files --> [autoscan*] --> [configure.scan] --> configure.ac

configure.ac --.
| .------> autoconf* -----> configure
[aclocal.m4] --+---+
| `-----> [autoheader*] --> [config.h.in]
[acsite.m4] ---'

Makefile.in -------------------------------> Makefile.in

Files used in configuring a software package:
.-------------> [config.cache]
configure* ------------+-------------> config.log
|
[config.h.in] -. v .-> [config.h] -.
+--> config.status* -+ +--> make*
Makefile.in ---' `-> Makefile ---'

* Menu:

File: autoconf.info, Node: Writing configure.ac, Next: autoscan Invocation, Up: Making configure Scripts

Writing `configure.ac'
======================

To produce a `configure' script for a software package, create a file
called `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 *Note Existing
Tests::, for their descriptions. For most other features, you can use
Autoconf template macros to produce custom checks; see *Note Writing
Tests::, for information about them. For especially tricky or
specialized features, `configure.ac' might need to contain some
hand-crafted shell commands; see *Note Portable Shell::. The
`autoscan' program can give you a good start in writing `configure.ac'
(*note autoscan Invocation::, for more information).

Previous versions of Autoconf promoted the name `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
`config.h.in' and so on (for which `.in' means "to be processed by
`configure'"). Using `configure.ac' is now preferred.

* Menu:

* Shell Script Compiler:: Autoconf as solution of a problem
* Autoconf Language:: Programming in Autoconf
* configure.ac Layout:: Standard organization of `configure.ac'

File: autoconf.info, Node: Shell Script Compiler, Next: Autoconf Language, Up: Writing configure.ac

A Shell Script Compiler
-----------------------

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

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

Naturally, you might then think of shell scripts; who needs
`autoconf'? A set of properly written shell functions is enough to
make it easy to write `configure' scripts by hand. Sigh!
Unfortunately, shell functions do not belong to the least common
denominator; therefore, where you would like to define a function and
use it ten times, you would instead need to copy its body ten times.

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

How does `autoconf' perform this task?

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

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

File: autoconf.info, Node: Autoconf Language, Next: configure.ac Layout, Prev: Shell Script Compiler, Up: Writing configure.ac

The Autoconf Language
---------------------

The Autoconf language is very different from many other computer
languages because it treats actual code the same as plain text. Whereas
in C, for instance, data and instructions have very 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 blank
space between the macro name and the open parenthesis. Arguments should
be enclosed within the M4 quote characters `[' and `]', and be
separated by commas. Any leading spaces in arguments are ignored,
unless they are quoted. You may safely leave out the quotes when the
argument is simple text, but _always_ quote complex arguments such as
other macro calls. This rule applies recursively for every macro call,
including macros called from other macros.

For instance:

AC_CHECK_HEADER([stdio.h],
[AC_DEFINE([HAVE_STDIO_H])],
[AC_MSG_ERROR([Sorry, can't do anything for you])])

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

AC_CHECK_HEADER(stdio.h,
[AC_DEFINE(HAVE_STDIO_H)],
[AC_MSG_ERROR([Sorry, can't do anything for you])])

Notice that the argument of `AC_MSG_ERROR' is still quoted; otherwise,
its comma would have been interpreted as an argument separator.

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

AC_CHECK_HEADER(stdio.h,
AC_DEFINE(HAVE_STDIO_H),
AC_MSG_ERROR([Sorry, can't do anything for you]))

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:

echo "Hard rock was here! --[AC_DC]"

which will result in

echo "Hard rock was here! --AC_DC"

When you use the same text in a macro argument, you must therefore have
an extra quotation level (since one is stripped away by the macro
substitution). In general, then, it is a good idea to _use double
quoting for all literal string arguments_:

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

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

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

is incorrect: here, the first argument of `AC_COMPILE_IFELSE' is `char
b[10];' and will be expanded once, which results in `char b10;'.
(There was an idiom common in Autoconf's past to address this issue via
the M4 `changequote' primitive, but do not use it!) Let's take a
closer look: the author meant the first argument to be understood as a
literal, and therefore it must be quoted twice:

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

Voila`, you actually produce `char b[10];' this time!

The careful reader will notice that, according to these guidelines,
the "properly" quoted `AC_CHECK_HEADER' example above is actually
lacking three pairs of quotes! Nevertheless, for the sake of
readability, double quotation of literals is used only where needed in
this manual.

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

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

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

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

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

File: autoconf.info, Node: configure.ac Layout, Prev: Autoconf Language, Up: Writing configure.ac

Standard `configure.ac' Layout
------------------------------

The order in which `configure.ac' calls the Autoconf macros is not
important, with a few exceptions. Every `configure.ac' must contain a
call to `AC_INIT' before the checks, and a call to `AC_OUTPUT' at the
end (*note 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 (*note Existing Tests::), and they also warn
you when `configure' is created if they are called out of order.

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

Autoconf requirements
`AC_INIT(PACKAGE, VERSION, BUG-REPORT-ADDRESS)'
information on the package
checks for programs
checks for libraries
checks for header files
checks for types
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
`AC_CONFIG_FILES([FILE...])'
`AC_OUTPUT'

File: autoconf.info, Node: autoscan Invocation, Next: ifnames Invocation, Prev: Writing configure.ac, Up: Making configure Scripts

Using `autoscan' to Create `configure.ac'
=========================================

The `autoscan' program can help you create and/or maintain a
`configure.ac' file for a software package. `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
`configure.scan' which is a preliminary `configure.ac' for that
package, and checks a possibly existing `configure.ac' for completeness.

When using `autoscan' to create a `configure.ac', you should
manually examine `configure.scan' before renaming it to `configure.ac';
it will probably need some adjustments. Occasionally, `autoscan'
outputs a macro in the wrong order relative to another macro, so that
`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 `AC_CONFIG_HEADERS' (*note Configuration Headers::).
You might also have to change or add some `#if' directives to your
program in order to make it work with Autoconf (*note ifnames
Invocation::, for information about a program that can help with that
job).

When using `autoscan' to maintain a `configure.ac', simply consider
adding its suggestions. The file `autoscan.log' will contain detailed
information on why a macro is requested.

`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, whitespace, and the Autoconf macro to
output if that symbol is encountered. Lines starting with `#' are
comments.

`autoscan' accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
`-v'
Print the names of the files it examines and the potentially
interesting symbols it finds in them. This output can be
voluminous.

`--include=DIR'
`-I DIR'
Append DIR to the include path. Multiple invocations accumulate.

`--prepend-include=DIR'

`-B DIR'
Prepend DIR to the include path. Multiple invocations accumulate.

File: autoconf.info, Node: ifnames Invocation, Next: autoconf Invocation, Prev: autoscan Invocation, Up: Making configure Scripts

Using `ifnames' to List Conditionals
====================================

`ifnames' can help you write `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, `ifnames' can thus help you figure out what its
`configure' needs to check for. It may help fill in some gaps in a
`configure.ac' generated by `autoscan' (*note autoscan Invocation::).

`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 `#if', `#elif', `#ifdef', or `#ifndef' directives. It prints each
identifier on a line, followed by a space-separated list of the files
in which that identifier occurs.

`ifnames' accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

File: autoconf.info, Node: autoconf Invocation, Next: autoreconf Invocation, Prev: ifnames Invocation, Up: Making configure Scripts

Using `autoconf' to Create `configure'
======================================

To create `configure' from `configure.ac', run the `autoconf' program
with no arguments. `autoconf' processes `configure.ac' with the M4
macro processor, using the Autoconf macros. If you give `autoconf' an
argument, it reads that file instead of `configure.ac' and writes the
configuration script to the standard output instead of to `configure'.
If you give `autoconf' the argument `-', it reads from the standard
input instead of `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; `autoconf' reads them first. Then it
looks for the optional file `acsite.m4' in the directory that contains
the distributed Autoconf macro files, and for the optional file
`aclocal.m4' in the current directory. Those files can contain your
site's or the package's own Autoconf macro definitions (*note Writing
Autoconf Macros::, for more information). If a macro is defined in
more than one of the files that `autoconf' reads, the last definition
it reads overrides the earlier ones.

`autoconf' accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
`-v'
Report processing steps.

`--debug'
`-d'
Don't remove the temporary files.

`--force'
`-f'
Remake `configure' even if newer than its input files.

`--include=DIR'
`-I DIR'
Append DIR to the include path. Multiple invocations accumulate.

`--prepend-include=DIR'

`-B DIR'
Prepend DIR to the include path. Multiple invocations accumulate.

`--output=FILE'
`-o FILE'
Save output (script or trace) to FILE. The file `-' stands for
the standard output.

`--warnings=CATEGORY'
`-W CATEGORY'
Report the warnings related to CATEGORY (which can actually be a
comma separated list). *Note Reporting Messages::, macro
`AC_DIAGNOSE', for a comprehensive list of categories. Special
values include:

`all'
report all the warnings

`none'
report none

`error'
treats warnings as errors

`no-CATEGORY'
disable warnings falling into CATEGORY

Warnings about `syntax' are enabled by default, and the environment
variable `WARNINGS', a comma separated list of categories, is
honored. Passing `-W CATEGORY' will actually behave as if you had
passed `--warnings=syntax,$WARNINGS,CATEGORY'. If you want to
disable the defaults and `WARNINGS', but (for example) enable the
warnings about obsolete constructs, you would use `-W
none,obsolete'.

Because `autoconf' uses `autom4te' behind the scenes, it displays
a back trace for errors, but not for warnings; if you want them,
just pass `-W error'. *Note autom4te Invocation::, for some
examples.

`--trace=MACRO[:FORMAT]'
`-t MACRO[:FORMAT]'
Do not create the `configure' script, but list the calls to MACRO
according to the FORMAT. Multiple `--trace' arguments can be used
to list several macros. Multiple `--trace' arguments for a single
macro are not cumulative; instead, you should just make FORMAT as
long as needed.

The FORMAT is a regular string, with newlines if desired, and
several special escape codes. It defaults to `$f:$l:$n:$%'; see
*Note autom4te Invocation::, for details on the FORMAT.

`--initialization'
`-i'
By default, `--trace' does not trace the initialization of the
Autoconf macros (typically the `AC_DEFUN' definitions). This
results in a noticeable speedup, but can be disabled by this
option.

It is often necessary to check the content of a `configure.ac' file,
but parsing it yourself is extremely fragile and error-prone. It is
suggested that you rely upon `--trace' to scan `configure.ac'. For
instance, to find the list of variables that are substituted, use:

$ 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
More traces deleted

The example below highlights the difference between `$@', `$*', and
*$%*.

$ cat configure.ac
AC_DEFINE(This, is, [an
[example]])
$ autoconf -t 'AC_DEFINE:@: $@
*: $*
$: $%'
@: [This],[is],[an
[example]]
*: This,is,an
[example]
$: This:is:an [example]

The FORMAT gives you a lot of freedom:

$ 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";
More traces deleted

A long 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):

$ autoconf -t 'AM_MISSING_PROG:${|:::::|}*'
ACLOCAL|:::::|aclocal|:::::|$missing_dir
AUTOCONF|:::::|autoconf|:::::|$missing_dir
AUTOMAKE|:::::|automake|:::::|$missing_dir
More traces deleted

File: autoconf.info, Node: autoreconf Invocation, Prev: autoconf Invocation, Up: Making configure Scripts

Using `autoreconf' to Update `configure' Scripts
================================================

Installing the various components of the GNU Build System can be
tedious: running `autopoint' for Gettext, `automake' for `Makefile.in'
etc. in each directory. It may be needed either because some tools
such as `automake' have been updated on your system, or because some of
the sources such as `configure.ac' have been updated, or finally,
simply in order to install the GNU Build System in a fresh tree.

`autoreconf' runs `autoconf', `autoheader', `aclocal', `automake',
`libtoolize', and `autopoint' (when appropriate) repeatedly to update
the GNU Build System in the specified directories and their
subdirectories (*note Subdirectories::). By default, it only remakes
those files that are older than their sources.

If you install a new version of some tool, you can make `autoreconf'
remake _all_ of the files by giving it the `--force' option.

*Note Automatic Remaking::, for `Makefile' rules to automatically
remake `configure' scripts when their source files change. That method
handles the timestamps of configuration header templates properly, but
does not pass `--autoconf-dir=DIR' or `--localdir=DIR'.

`autoreconf' accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
Print the name of each directory where `autoreconf' runs
`autoconf' (and `autoheader', if appropriate).

`--debug'
`-d'
Don't remove the temporary files.

`--force'
`-f'
Remake even `configure' scripts and configuration headers that are
newer than their input files (`configure.ac' and, if present,
`aclocal.m4').

`--install'
`-i'
Install the missing auxiliary files in the package. By default,
files are copied; this can be changed with `--symlink'.

This option triggers calls to `automake --add-missing',
`libtoolize', `autopoint', etc.

`--symlink'
`-s'
When used with `--install', install symbolic links to the missing
auxiliary files instead of copying them.

`--make'
`-m'
When the directories were configured, update the configuration by
running `./config.status --recheck && ./config.status', and then
run `make'.

`--include=DIR'
`-I DIR'
Append DIR to the include path. Multiple invocations accumulate.

`--prepend-include=DIR'

`-B DIR'
Prepend DIR to the include path. Multiple invocations accumulate.

`--warnings=CATEGORY'
`-W CATEGORY'
Report the warnings related to CATEGORY (which can actually be a
comma separated list).

`cross'
related to cross compilation issues.

`obsolete'
report the uses of obsolete constructs.

`portability'
portability issues

`syntax'
dubious syntactic constructs.

`all'
report all the warnings

`none'
report none

`error'
treats warnings as errors

`no-CATEGORY'
disable warnings falling into CATEGORY

File: autoconf.info, Node: Setup, Next: Existing Tests, Prev: Making configure Scripts, Up: Top

Initialization and Output Files
*******************************

Autoconf-generated `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:

File: autoconf.info, Node: Initializing configure, Next: Notices, Up: Setup

Initializing `configure'
========================

Every `configure' script must call `AC_INIT' before doing anything
else. The only other required macro is `AC_OUTPUT' (*note Output::).

- Macro: AC_INIT (PACKAGE, VERSION, [BUG-REPORT], [TARNAME])
Process any command-line arguments and perform various
initializations and verifications.

Set the name of the PACKAGE and its VERSION. These are typically
used in `--version' support, including that of `configure'. The
optional argument BUG-REPORT should be the email to which users
should send bug reports. The package TARNAME differs from
PACKAGE: the latter designates the full package name (e.g., `GNU
Autoconf'), while the former is meant for distribution tar ball
names (e.g., `autoconf'). It defaults to PACKAGE with `GNU '
stripped, lower-cased, and all characters other than alphanumerics
and underscores are changed to `-'.

It is preferable that the arguments of `AC_INIT' be static, i.e.,
there should not be any shell computation, but they can be
computed by M4.

The following M4 macros (e.g., `AC_PACKAGE_NAME'), output variables
(e.g., `PACKAGE_NAME'), and preprocessor symbols (e.g.,
`PACKAGE_NAME') are defined by `AC_INIT':

`AC_PACKAGE_NAME', `PACKAGE_NAME'
Exactly PACKAGE.

`AC_PACKAGE_TARNAME', `PACKAGE_TARNAME'
Exactly TARNAME.

`AC_PACKAGE_VERSION', `PACKAGE_VERSION'
Exactly VERSION.

`AC_PACKAGE_STRING', `PACKAGE_STRING'
Exactly `PACKAGE VERSION'.

`AC_PACKAGE_BUGREPORT', `PACKAGE_BUGREPORT'
Exactly BUG-REPORT.

File: autoconf.info, Node: Notices, Next: Input, Prev: Initializing configure, Up: Setup

Notices in `configure'
======================

The following macros manage version numbers for `configure' scripts.
Using them is optional.

- Macro: AC_PREREQ (VERSION)
Ensure that a recent enough version of Autoconf is being used. If
the version of Autoconf being used to create `configure' is
earlier than VERSION, print an error message to the standard error
output and exit with failure (exit status is 63). For example:

AC_PREREQ(2.59)

This macro is the only macro that may be used before `AC_INIT', but
for consistency, you are invited not to do so.

- Macro: AC_COPYRIGHT (COPYRIGHT-NOTICE)
State that, in addition to the Free Software Foundation's
copyright on the Autoconf macros, parts of your `configure' are
covered by the COPYRIGHT-NOTICE.

The COPYRIGHT-NOTICE will show up in both the head of `configure'
and in `configure --version'.

- Macro: AC_REVISION (REVISION-INFO)
Copy revision stamp REVISION-INFO into the `configure' script,
with any dollar signs or double-quotes removed. This macro lets
you put a revision stamp from `configure.ac' into `configure'
without RCS or CVS changing it when you check in `configure'.
That way, you can determine easily which revision of
`configure.ac' a particular `configure' corresponds to.

For example, this line in `configure.ac':

AC_REVISION($Revision: 1.30 $)

produces this in `configure':

#! /bin/sh
# From configure.ac Revision: 1.30

File: autoconf.info, Node: Input, Next: Output, Prev: Notices, Up: Setup

Finding `configure' Input
=========================

- Macro: AC_CONFIG_SRCDIR (UNIQUE-FILE-IN-SOURCE-DIR)
UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the package's
source directory; `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 `--srcdir'; this is a safety check. *Note
configure Invocation::, for more information.

Packages that do manual configuration or use the `install' program
might need to tell `configure' where to find some other shell scripts
by calling `AC_CONFIG_AUX_DIR', though the default places it looks are
correct for most cases.

- Macro: AC_CONFIG_AUX_DIR (DIR)
Use the auxiliary build tools (e.g., `install-sh', `config.sub',
`config.guess', Cygnus `configure', Automake and Libtool scripts
etc.) that are in directory DIR. These are auxiliary files used
in configuration. DIR can be either absolute or relative to
`SRCDIR'. The default is `SRCDIR' or `SRCDIR/..' or
`SRCDIR/../..', whichever is the first that contains `install-sh'.
The other files are not checked for, so that using
`AC_PROG_INSTALL' does not automatically require distributing the
other auxiliary files. It checks for `install.sh' also, but that
name is obsolete because some `make' have a rule that creates
`install' from it if there is no `Makefile'.

Similarly, packages that use `aclocal' should declare where local
macros can be found using `AC_CONFIG_MACRO_DIR'.

- Macro: AC_CONFIG_MACRO_DIR (DIR)
Future versions of `autopoint', `libtoolize', `aclocal' and
`autoreconf' will use directory DIR as the location of additional
local Autoconf macros. Be sure to call this macro directly from
`configure.ac' so that tools that install macros for `aclocal' can
find the declaration before `--trace' can be called safely.

File: autoconf.info, Node: Output, Next: Configuration Actions, Prev: Input, Up: Setup

Outputting Files
================

Every Autoconf script, e.g., `configure.ac', should finish by calling
`AC_OUTPUT'. That is the macro that generates and runs
`config.status', which will create the `Makefile's and any other files
resulting from configuration. This is the only required macro besides
`AC_INIT' (*note Input::).

- Macro: AC_OUTPUT
Generate `config.status' and launch it. Call this macro once, at
the end of `configure.ac'.

`config.status' will perform all the configuration actions: all the
output files (see *Note Configuration Files::, macro
`AC_CONFIG_FILES'), header files (see *Note Configuration
Headers::, macro `AC_CONFIG_HEADERS'), commands (see *Note
Configuration Commands::, macro `AC_CONFIG_COMMANDS'), links (see
*Note Configuration Links::, macro `AC_CONFIG_LINKS'),
subdirectories to configure (see *Note Subdirectories::, macro
`AC_CONFIG_SUBDIRS') are honored.

The location of your `AC_OUTPUT' invocation is the exact point
where configuration actions are taken: any code afterwards will be
executed by `configure' once `config.status' was run. If you want
to bind actions to `config.status' itself (independently of
whether `configure' is being run), see *Note Running Arbitrary
Configuration Commands: Configuration Commands.

Historically, the usage of `AC_OUTPUT' was somewhat different.
*Note Obsolete Macros::, for a description of the arguments that
`AC_OUTPUT' used to support.

If you run `make' in subdirectories, you should run it using the
`make' variable `MAKE'. Most versions of `make' set `MAKE' to the name
of the `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 `make' do
not set this variable. The following macro allows you to use it even
with those versions.

- Macro: AC_PROG_MAKE_SET
If `make' predefines the Make variable `MAKE', define output
variable `SET_MAKE' to be empty. Otherwise, define `SET_MAKE' to
contain `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'.

If you use this macro, place a line like this in each `Makefile.in'
that runs `MAKE' on other directories:

@SET_MAKE@

File: autoconf.info, Node: Configuration Actions, Next: Configuration Files, Prev: Output, Up: Setup

Performing Configuration Actions
================================

`configure' is designed so that it appears to do everything itself, but
there is actually a hidden slave: `config.status'. `configure' is in
charge of examining your system, but it is `config.status' that
actually takes the proper actions based on the results of `configure'.
The most typical task of `config.status' is to _instantiate_ files.

This section describes the common behavior of the four standard
instantiating macros: `AC_CONFIG_FILES', `AC_CONFIG_HEADERS',
`AC_CONFIG_COMMANDS' and `AC_CONFIG_LINKS'. They all have this
prototype:

AC_CONFIG_FOOS(TAG..., [COMMANDS], [INIT-CMDS])

where the arguments are:

TAG...
A whitespace-separated list of tags, which are typically the names
of the files to instantiate.

You are encouraged to use literals as TAGS. In particular, you
should avoid

... && my_foos="$my_foos fooo"
... && my_foos="$my_foos foooo"
AC_CONFIG_FOOS($my_foos)

and use this instead:

... && AC_CONFIG_FOOS(fooo)
... && AC_CONFIG_FOOS(foooo)

The macros `AC_CONFIG_FILES' and `AC_CONFIG_HEADERS' use special
TAGs: they may have the form `OUTPUT' or `OUTPUT:INPUTS'. The
file OUTPUT is instantiated from its templates, INPUTS (defaulting
to `OUTPUT.in').

For instance
`AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)' asks for
the creation of `Makefile' that will be the expansion of the
output variables in the concatenation of `boiler/top.mk' and
`boiler/bot.mk'.

The special value `-' might be used to denote the standard output
when used in OUTPUT, or the standard input when used in the
INPUTS. You most probably don't need to use this in
`configure.ac', but it is convenient when using the command line
interface of `./config.status', see *Note config.status
Invocation::, for more details.

The INPUTS may be absolute or relative filenames. In the latter
case they are first looked for in the build tree, and then in the
source tree.

COMMANDS
Shell commands output literally into `config.status', and
associated with a tag that the user can use to tell `config.status'
which the commands to run. The commands are run each time a TAG
request is given to `config.status', typically each time the file
`TAG' is created.

The variables set during the execution of `configure' are _not_
available here: you first need to set them via the INIT-CMDS.
Nonetheless the following variables are precomputed:

`srcdir'
The path from the top build directory to the top source
directory. This is what `configure''s option `--srcdir' sets.

`ac_top_srcdir'
The path from the current build directory to the top source
directory.

`ac_top_builddir'
The path from the current build directory to the top build
directory. It can be empty, or else ends with a slash, so
that you may concatenate it.

`ac_srcdir'
The path from the current build directory to the
corresponding source directory.

The "current" directory refers to the directory (or
pseudo-directory) containing the input part of TAGS. For
instance, running

AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [...], [...])

with `--srcdir=../package' produces the following values:

# Argument of --srcdir
srcdir='../package'
# Reversing deep/dir
ac_top_builddir='../../'
# Concatenation of $ac_top_builddir and srcdir
ac_top_srcdir='../../../package'
# Concatenation of $ac_top_srcdir and deep/dir
ac_srcdir='../../../package/deep/dir'

independently of `in/in.in'.

INIT-CMDS
Shell commands output _unquoted_ near the beginning of
`config.status', and executed each time `config.status' runs
(regardless of the tag). Because they are unquoted, for example,
`$var' will be output as the value of `var'. INIT-CMDS is
typically used by `configure' to give `config.status' some
variables it needs to run the COMMANDS.

You should be extremely cautious in your variable names: all the
INIT-CMDS share the same name space and may overwrite each other
in unpredictable ways. Sorry....

All these macros can be called multiple times, with different TAGs,
of course!

File: autoconf.info, Node: Configuration Files, Next: Makefile Substitutions, Prev: Configuration Actions, Up: Setup

Creating Configuration Files
============================

Be sure to read the previous section, *Note Configuration Actions::.

- Macro: AC_CONFIG_FILES (FILE..., [CMDS], [INIT-CMDS])
Make `AC_OUTPUT' create each `FILE' by copying an input file (by
default `FILE.in'), substituting the output variable values. This
macro is one of the instantiating macros; see *Note Configuration
Actions::. *Note Makefile Substitutions::, for more information
on using output variables. *Note 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,
`Makefile's are created this way, but other files, such as
`.gdbinit', can be specified as well.

Typical calls to `AC_CONFIG_FILES' look like this:

AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
AC_CONFIG_FILES([autoconf], [chmod +x autoconf])

You can override an input file name by appending to FILE a
colon-separated list of input files. Examples:

AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
[lib/Makefile:boiler/lib.mk])

Doing this allows you to keep your file names acceptable to
MS-DOS, or to prepend and/or append boilerplate to the file.

File: autoconf.info, Node: Makefile Substitutions, Next: Configuration Headers, Prev: Configuration Files, Up: Setup

Substitutions in Makefiles
==========================

Each subdirectory in a distribution that contains something to be
compiled or installed should come with a file `Makefile.in', from which
`configure' will create a `Makefile' in that directory. To create a
`Makefile', `configure' performs a simple variable substitution,
replacing occurrences of `@VARIABLE@' in `Makefile.in' with the value
that `configure' has determined for that variable. Variables that are
substituted into output files in this way are called "output
variables". They are ordinary shell variables that are set in
`configure'. To make `configure' substitute a particular variable into
the output files, the macro `AC_SUBST' must be called with that
variable name as an argument. Any occurrences of `@VARIABLE@' for
other variables are left unchanged. *Note Setting Output Variables::,
for more information on creating output variables with `AC_SUBST'.

A software package that uses a `configure' script should be
distributed with a file `Makefile.in', but no `Makefile'; that way, the
user has to properly configure the package for the local system before
compiling it.

*Note Makefile Conventions: (standards)Makefile Conventions, for
more information on what to put in `Makefile's.

* Menu:

File: autoconf.info, Node: Preset Output Variables, Next: Installation Directory Variables, Up: Makefile Substitutions

Preset Output Variables
-----------------------

Some output variables are preset by the Autoconf macros. Some of the
Autoconf macros set additional output variables, which are mentioned in
the descriptions for those macros. *Note Output Variable Index::, for a
complete list of output variables. *Note Installation Directory
Variables::, for the list of the preset ones related to installation
directories. Below are listed the other preset ones. They all are
precious variables (*note Setting Output Variables::, `AC_ARG_VAR').

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

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

#! /bin/sh
# @configure_input@

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

- Variable: CPPFLAGS
Header file search directory (`-IDIR') and any other miscellaneous
options for the C and C++ preprocessors and compilers. If it is
not set in the environment when `configure' runs, the default
value is empty. `configure' uses this variable when compiling or
preprocessing programs to test for C and C++ features.

- Variable: CXXFLAGS
Debugging and optimization options for the C++ compiler. If it is
not set in the environment when `configure' runs, the default
value is set when you call `AC_PROG_CXX' (or empty if you don't).
`configure' uses this variable when compiling programs to test for
C++ features.

- Variable: DEFS
`-D' options to pass to the C compiler. If `AC_CONFIG_HEADERS' is
called, `configure' replaces `@DEFS@' with `-DHAVE_CONFIG_H'
instead (*note Configuration Headers::). This variable is not
defined while `configure' is performing its tests, only when
creating the output files. *Note Setting Output Variables::, for
how to check the results of previous tests.

- Variable: ECHO_C
- Variable: ECHO_N
- Variable: ECHO_T
How does one suppress the trailing newline from `echo' for
question-answer message pairs? These variables provide a way:

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

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

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

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

- Variable: LDFLAGS
Stripping (`-s'), path (`-L'), and any other miscellaneous options
for the linker. Don't use this variable to pass library names
(`-l') to the linker, use `LIBS' instead. If it is not set in the
environment when `configure' runs, the default value is empty.
`configure' uses this variable when linking programs to test for
C, C++, and Fortran features.

- Variable: LIBS
`-l' options to pass to the linker. The default value is empty,
but some Autoconf macros may prepend extra libraries to this
variable if those libraries are found and provide necessary
functions, see *Note Libraries::. `configure' uses this variable
when linking programs to test for C, C++, and Fortran features.

- Variable: builddir
Rigorously equal to `.'. Added for symmetry only.

- Variable: abs_builddir
Absolute path of `builddir'.

- Variable: top_builddir
The relative path to the top-level of the current build tree. In
the top-level directory, this is the same as `builddir'.

- Variable: abs_top_builddir
Absolute path of `top_builddir'.

- Variable: srcdir
The relative path to the directory that contains the source code
for that `Makefile'.

- Variable: abs_srcdir
Absolute path of `srcdir'.

- Variable: top_srcdir
The relative path to the top-level source code directory for the
package. In the top-level directory, this is the same as `srcdir'.

- Variable: abs_top_srcdir
Absolute path of `top_srcdir'.

File: autoconf.info, Node: Installation Directory Variables, Next: Build Directories, Prev: Preset Output Variables, Up: Makefile Substitutions

Installation Directory Variables
--------------------------------

The following variables specify the directories where the package will
be installed, see *Note Variables for Installation Directories:
(standards)Directory Variables, for more information. See the end of
this section for details on when and how to use these variables.

- Variable: bindir
The directory for installing executables that users run.

- Variable: datadir
The directory for installing read-only architecture-independent
data.

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

- Variable: includedir
The directory for installing C header files.

- Variable: infodir
The directory for installing documentation in Info format.

- Variable: libdir
The directory for installing object code libraries.

- Variable: libexecdir
The directory for installing executables that other programs run.

- Variable: localstatedir
The directory for installing modifiable single-machine data.

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

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

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

- Variable: sbindir
The directory for installing executables that system
administrators run.

- Variable: sharedstatedir
The directory for installing modifiable architecture-independent
data.

- Variable: sysconfdir
The directory for installing read-only single-machine data.

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

This behavior is mandated by the GNU coding standards, so that when
the user runs:

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

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

In order to support these features, it is essential that `datadir'
remains being defined as `${prefix}/share' to depend upon the current
value of `prefix'.

A corollary is that you should not use these variables except in
Makefiles. For instance, instead of trying to evaluate `datadir' in
`configure' and hard-coding it in Makefiles using e.g.,
`AC_DEFINE_UNQUOTED(DATADIR, "$datadir")', you should add
`-DDATADIR="$(datadir)"' to your `CPPFLAGS'.

Similarly you should not rely on `AC_OUTPUT_FILES' to replace
`datadir' and friends in your shell scripts and other files, rather let
`make' manage their replacement. For instance Autoconf ships templates
of its shell scripts ending with `.in', and uses a Makefile snippet
similar to:

edit = sed \
-e 's,@datadir\@,$(pkgdatadir),g' \
-e 's,@prefix\@,$(prefix),g'

autoconf: Makefile $(srcdir)/autoconf.in
rm -f autoconf autoconf.tmp
$(edit) $(srcdir)/autoconf.in >autoconf.tmp
chmod +x autoconf.tmp
mv autoconf.tmp autoconf

autoheader: Makefile $(srcdir)/autoheader.in
rm -f autoheader autoheader.tmp
$(edit) $(srcdir)/autoconf.in >autoheader.tmp
chmod +x autoheader.tmp
mv autoheader.tmp autoheader

Some details are noteworthy:

`@datadir\@'
The backslash prevents `configure' from replacing `@datadir@' in
the sed expression itself.

`$(pkgdatadir)'
Don't use `@pkgdatadir@'! Use the matching makefile variable
instead.

`,'
Don't use `/' in the sed expression(s) since most likely the
variables you use, such as `$(pkgdatadir)', will contain some.

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

`Separated dependencies and Single Suffix Rules'
You can't use them! The above snippet cannot be (portably)
rewritten as:

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

*Note Limitations of Make::, for details.

``$(srcdir)''
Be sure to specify the path to the sources, otherwise the package
won't support separated builds.

File: autoconf.info, Node: Build Directories, Next: Automatic Remaking, Prev: Installation Directory Variables, Up: Makefile Substitutions

Build Directories
-----------------

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

To support doing this, `make' uses the `VPATH' variable to find the
files that are in the source directory. GNU Make and most other recent
`make' programs can do this. Older `make' programs do not support
`VPATH'; when using them, the source code must be in the same directory
as the object files.

To support `VPATH', each `Makefile.in' should contain two lines that
look like:

srcdir = @srcdir@
VPATH = @srcdir@

Do not set `VPATH' to the value of another variable, for example
`VPATH = $(srcdir)', because some versions of `make' do not do variable
substitutions on the value of `VPATH'.

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

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

Instead, `Makefile' command lines should always refer to source
files by prefixing them with `$(srcdir)/'. For example:

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

File: autoconf.info, Node: Automatic Remaking, Prev: Build Directories, Up: Makefile Substitutions

Automatic Remaking
------------------

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

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

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

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

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

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

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

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

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

In addition, you should use `AC_CONFIG_FILES([stamp-h], [echo
timestamp > stamp-h])' so `config.status' will ensure that `config.h'
is considered up to date. *Note Output::, for more information about
`AC_OUTPUT'.

*Note config.status Invocation::, for more examples of handling
configuration-related dependencies.

File: autoconf.info, Node: Configuration Headers, Next: Configuration Commands, Prev: Makefile Substitutions, Up: Setup

Configuration Header Files
==========================

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

The package should `#include' the configuration header file before
any other header files, to prevent inconsistencies in declarations (for
example, if it redefines `const'). Use `#include <config.h>' instead
of `#include "config.h"', and pass the C compiler a `-I.' option (or
`-I..'; whichever directory contains `config.h'). That way, even if
the source directory is configured itself (perhaps to make a
distribution), other build directories can also be configured without
finding the `config.h' from the source directory.

- Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS])
This macro is one of the instantiating macros; see *Note
Configuration Actions::. Make `AC_OUTPUT' create the file(s) in
the whitespace-separated list HEADER containing C preprocessor
`#define' statements, and replace `@DEFS@' in generated files with
`-DHAVE_CONFIG_H' instead of the value of `DEFS'. The usual name
for HEADER is `config.h'.

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

Usually the input file is named `HEADER.in'; however, you can
override the input file name by appending to HEADER a
colon-separated list of input files. Examples:

AC_CONFIG_HEADERS([config.h:config.hin])
AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])

Doing this allows you to keep your file names acceptable to
MS-DOS, or to prepend and/or append boilerplate to the file.

*Note Configuration Actions::, for more details on HEADER.

* Menu:

* Header Templates:: Input for the configuration headers
* autoheader Invocation:: How to create configuration templates
* Autoheader Macros:: How to specify CPP templates

File: autoconf.info, Node: Header Templates, Next: autoheader Invocation, Up: Configuration Headers

Configuration Header Templates
------------------------------

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

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

Then you could have code like the following in `conf.h.in'. On systems
that have `unistd.h', `configure' will `#define' `HAVE_UNISTD_H' to 1.
On other systems, the whole line will be commented out (in case the
system predefines that symbol).

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

Pay attention that `#undef' is in the first column, and there is
nothing behind `HAVE_UNISTD_H', not even white spaces. You can then
decode the configuration header using the preprocessor directives:

#include <conf.h>

#if HAVE_UNISTD_H
# include <unistd.h>
#else
/* We are in trouble. */
#endif

The use of old form templates, with `#define' instead of `#undef' is
strongly discouraged. Similarly with old templates with comments on
the same line as the `#undef'. Anyway, putting comments in
preprocessor macros has never been a good idea.

Since it is a tedious task to keep a template header up to date, you
may use `autoheader' to generate it, see *Note autoheader Invocation::.

File: autoconf.info, Node: autoheader Invocation, Next: Autoheader Macros, Prev: Header Templates, Up: Configuration Headers

Using `autoheader' to Create `config.h.in'
------------------------------------------

The `autoheader' program can create a template file of C `#define'
statements for `configure' to use. If `configure.ac' invokes
`AC_CONFIG_HEADERS(FILE)', `autoheader' creates `FILE.in'; if multiple
file arguments are given, the first one is used. Otherwise,
`autoheader' creates `config.h.in'.

In order to do its job, `autoheader' needs you to document all of
the symbols that you might use; i.e., there must be at least one
`AC_DEFINE' or one `AC_DEFINE_UNQUOTED' call with a third argument for
each symbol (*note Defining Symbols::). An additional constraint is
that the first argument of `AC_DEFINE' must be a literal. Note that
all symbols defined by Autoconf's builtin tests are already documented
properly; you only need to document those that you define yourself.

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

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

But let's come back to the point: `autoheader''s invocation...

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

`autoheader' accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
`-v'
Report processing steps.

`--debug'
`-d'
Don't remove the temporary files.

`--force'
`-f'
Remake the template file even if newer than its input files.

`--include=DIR'
`-I DIR'
Append DIR to include path. Multiple invocations accumulate.

`--prepend-include=DIR'

`-B DIR'
Prepend DIR to include path. Multiple invocations accumulate.

`--warnings=CATEGORY'
`-W CATEGORY'
Report the warnings related to CATEGORY (which can actually be a
comma separated list). Current categories include:

`obsolete'
report the uses of obsolete constructs

`all'
report all the warnings

`none'
report none

`error'
treats warnings as errors

`no-CATEGORY'
disable warnings falling into CATEGORY

File: autoconf.info, Node: Autoheader Macros, Prev: autoheader Invocation, Up: Configuration Headers

Autoheader Macros
-----------------

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

The simplest way to create a template for a SYMBOL is to supply the
DESCRIPTION argument to an `AC_DEFINE(SYMBOL)'; see *Note Defining
Symbols::. You may also use one of the following macros.

- Macro: AH_VERBATIM (KEY, TEMPLATE)
Tell `autoheader' to include the TEMPLATE as-is in the header
template file. This TEMPLATE is associated with the KEY, which is
used to sort all the different templates and guarantee their
uniqueness. It should be a symbol that can be `AC_DEFINE''d.

For example:

AH_VERBATIM([_GNU_SOURCE],
[/* Enable GNU extensions on systems that have them. */
#ifndef _GNU_SOURCE
# define _GNU_SOURCE
#endif])

- Macro: AH_TEMPLATE (KEY, DESCRIPTION)
Tell `autoheader' to generate a template for KEY. This macro
generates standard templates just like `AC_DEFINE' when a
DESCRIPTION is given.

For example:

AH_TEMPLATE([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.])

will generate the following template, with the description properly
justified.

/* 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

- Macro: AH_TOP (TEXT)
Include TEXT at the top of the header template file.

- Macro: AH_BOTTOM (TEXT)
Include TEXT at the bottom of the header template file.

File: autoconf.info, Node: Configuration Commands, Next: Configuration Links, Prev: Configuration Headers, Up: Setup

Running Arbitrary Configuration Commands
========================================

You can execute arbitrary commands before, during, and after
`config.status' is run. The three following macros accumulate the
commands to run when they are called multiple times.
`AC_CONFIG_COMMANDS' replaces the obsolete macro `AC_OUTPUT_COMMANDS';
see *Note Obsolete Macros::, for details.

- Macro: AC_CONFIG_COMMANDS (TAG..., [CMDS], [INIT-CMDS])
Specify additional shell commands to run at the end of
`config.status', and shell commands to initialize any variables
from `configure'. Associate the commands with TAG. Since
typically the CMDS create a file, TAG should naturally be the name
of that file. If needed, the directory hosting TAG is created.
This macro is one of the instantiating macros; see *Note
Configuration Actions::.

Here is an unrealistic example:
fubar=42
AC_CONFIG_COMMANDS([fubar],
[echo this is extra $fubar, and so on.],
[fubar=$fubar])

Here is a better one:
AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])

- Macro: AC_CONFIG_COMMANDS_PRE (CMDS)
Execute the CMDS right before creating `config.status'.

- Macro: AC_CONFIG_COMMANDS_POST (CMDS)
Execute the CMDS right after creating `config.status'.

File: autoconf.info, Node: Configuration Links, Next: Subdirectories, Prev: Configuration Commands, Up: Setup

Creating Configuration Links
============================

You may find it convenient to create links whose destinations depend
upon results of tests. One can use `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.

- Macro: AC_CONFIG_LINKS (DEST:SOURCE..., [CMDS], [INIT-CMDS])
Make `AC_OUTPUT' link each of the existing files SOURCE to the
corresponding link name DEST. Makes a symbolic link if possible,
otherwise a hard link if possible, otherwise a copy. The DEST and
SOURCE names should be relative to the top level source or build
directory. This macro is one of the instantiating macros; see
*Note Configuration Actions::.

For example, this call:

AC_CONFIG_LINKS(host.h:config/$machine.h
object.h:config/$obj_format.h)

creates in the current directory `host.h' as a link to
`SRCDIR/config/$machine.h', and `object.h' as a link to
`SRCDIR/config/$obj_format.h'.

The tempting value `.' for DEST is invalid: it makes it impossible
for `config.status' to guess the links to establish.

One can then run:
./config.status host.h object.h

to create the links.

File: autoconf.info, Node: Subdirectories, Next: Default Prefix, Prev: Configuration Links, Up: Setup

Configuring Other Packages in Subdirectories
============================================

In most situations, calling `AC_OUTPUT' is sufficient to produce
`Makefile's in subdirectories. However, `configure' scripts that
control more than one independent package can use `AC_CONFIG_SUBDIRS'
to run `configure' scripts for other packages in subdirectories.

- Macro: AC_CONFIG_SUBDIRS (DIR ...)
Make `AC_OUTPUT' run `configure' in each subdirectory DIR in the
given whitespace-separated list. Each DIR should be a literal,
i.e., please do not use:

if test "$package_foo_enabled" = yes; then
$my_subdirs="$my_subdirs foo"
fi
AC_CONFIG_SUBDIRS($my_subdirs)

because this prevents `./configure --help=recursive' from
displaying the options of the package `foo'. Rather, you should
write:

if test "$package_foo_enabled" = yes; then
AC_CONFIG_SUBDIRS(foo)
fi

If a given DIR is not found, an error is reported: if the
subdirectory is optional, write:

if test -d $srcdir/foo; then
AC_CONFIG_SUBDIRS(foo)
fi

If a given DIR contains `configure.gnu', it is run instead of
`configure'. This is for packages that might use a non-Autoconf
script `Configure', which can't be called through a wrapper
`configure' since it would be the same file on case-insensitive
filesystems. Likewise, if a DIR contains `configure.in' but no
`configure', the Cygnus `configure' script found by
`AC_CONFIG_AUX_DIR' is used.

The subdirectory `configure' scripts are given the same command
line options that were given to this `configure' script, with minor
changes if needed, which include:

- adjusting a relative path for the cache file;

- adjusting a relative path for the source directory;

- propagating the current value of `$prefix', including if it
was defaulted, and if the default values of the top level and
of the subdirectory `configure' differ.

This macro also sets the output variable `subdirs' to the list of
directories `DIR ...'. `Makefile' rules can use this variable to
determine which subdirectories to recurse into.

This macro may be called multiple times.

File: autoconf.info, Node: Default Prefix, Prev: Subdirectories, Up: Setup

Default Prefix
==============

By default, `configure' sets the prefix for files it installs to
`/usr/local'. The user of `configure' can select a different prefix
using the `--prefix' and `--exec-prefix' options. There are two ways
to change the default: when creating `configure', and when running it.

Some software packages might want to install in a directory other
than `/usr/local' by default. To accomplish that, use the
`AC_PREFIX_DEFAULT' macro.

- Macro: AC_PREFIX_DEFAULT (PREFIX)
Set the default installation prefix to PREFIX instead of
`/usr/local'.

It may be convenient for users to have `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
`AC_PREFIX_PROGRAM'.

- Macro: AC_PREFIX_PROGRAM (PROGRAM)
If the user did not specify an installation prefix (using the
`--prefix' option), guess a value for it by looking for PROGRAM in
`PATH', the way the shell does. If PROGRAM is found, set the
prefix to the parent of the directory containing PROGRAM, else
default the prefix as described above (`/usr/local' or
`AC_PREFIX_DEFAULT'). For example, if PROGRAM is `gcc' and the
`PATH' contains `/usr/local/gnu/bin/gcc', set the prefix to
`/usr/local/gnu'.

File: autoconf.info, Node: Existing Tests, Next: Writing Tests, Prev: Setup, Up: Top

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 (*note 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
`configure' runs (*note Caching Results::).

Some of these macros set output variables. *Note Makefile
Substitutions::, for how to get their values. The phrase "define NAME"
is used below as a shorthand to mean "define C preprocessor symbol NAME
to the value 1". *Note Defining Symbols::, for how to get those symbol
definitions into your program.

* Menu:

File: autoconf.info, Node: Common Behavior, Next: Alternative Programs, Up: Existing Tests

Common 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

File: autoconf.info, Node: Standard Symbols, Next: Default Includes, Up: Common Behavior

Standard Symbols
----------------

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

For instance,

AC_CHECK_TYPES(struct $Expensive*)

will define the symbol `HAVE_STRUCT__EXPENSIVEP' if the check succeeds.

File: autoconf.info, Node: Default Includes, Prev: Standard Symbols, Up: Common Behavior

Default Includes
----------------

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:

#if TIME_WITH_SYS_TIME
# include <sys/time.h>
# include <time.h>
#else
# if HAVE_SYS_TIME_H
# include <sys/time.h>
# else
# include <time.h>
# endif
#endif

Unless you know exactly what you are doing, you should avoid using
unconditional includes, and check the existence of the headers you
include beforehand (*note Header Files::).

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

- Macro: AC_DEFAULT_INCLUDES ([INCLUDE-DIRECTIVES])
Expand to INCLUDE-DIRECTIVES if defined, otherwise to:

#include <stdio.h>
#if HAVE_SYS_TYPES_H
# include <sys/types.h>
#endif
#if HAVE_SYS_STAT_H
# include <sys/stat.h>
#endif
#if STDC_HEADERS
# include <stdlib.h>
# include <stddef.h>
#else
# if HAVE_STDLIB_H
# include <stdlib.h>
# endif
#endif
#if HAVE_STRING_H
# if !STDC_HEADERS && HAVE_MEMORY_H
# include <memory.h>
# endif
# include <string.h>
#endif
#if HAVE_STRINGS_H
# include <strings.h>
#endif
#if HAVE_INTTYPES_H
# include <inttypes.h>
#else
# if HAVE_STDINT_H
# include <stdint.h>
# endif
#endif
#if HAVE_UNISTD_H
# include <unistd.h>
#endif

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
`AC_HEADERS_STDC', nor check for `stdlib.h' etc.

These headers are checked for in the same order as they are
included. For instance, on some systems `string.h' and
`strings.h' both exist, but conflict. Then `HAVE_STRING_H' will
be defined, but `HAVE_STRINGS_H' won't.

File: autoconf.info, Node: Alternative Programs, Next: Files, Prev: Common Behavior, Up: Existing Tests

Alternative Programs
====================

These macros check for the presence or behavior of particular programs.
They are used to choose between several alternative programs and to
decide what to do once one has been chosen. If there is no macro
specifically defined to check for a program you need, and you don't need
to check for any special properties of it, then you can use one of the
general program-check macros.

* Menu:

* Particular Programs:: Special handling to find certain programs
* Generic Programs:: How to find other programs

File: autoconf.info, Node: Particular Programs, Next: Generic Programs, Up: Alternative Programs

Particular Program Checks
-------------------------

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

- Macro: AC_PROG_AWK
Check for `gawk', `mawk', `nawk', and `awk', in that order, and
set output variable `AWK' to the first one that is found. It
tries `gawk' first because that is reported to be the best
implementation.

- Macro: AC_PROG_EGREP
Check for `grep -E' and `egrep', in that order, and set output
variable `EGREP' to the first one that is found.

- Macro: AC_PROG_FGREP
Check for `grep -F' and `fgrep', in that order, and set output
variable `FGREP' to the first one that is found.

- Macro: AC_PROG_INSTALL
Set output variable `INSTALL' to the path of a BSD-compatible
`install' program, if one is found in the current `PATH'.
Otherwise, set `INSTALL' to `DIR/install-sh -c', checking the
directories specified to `AC_CONFIG_AUX_DIR' (or its default
directories) to determine DIR (*note Output::). Also set the
variables `INSTALL_PROGRAM' and `INSTALL_SCRIPT' to `${INSTALL}'
and `INSTALL_DATA' to `${INSTALL} -m 644'.

This macro screens out various instances of `install' known not to
work. It prefers to find a C program rather than a shell script,
for speed. Instead of `install-sh', it can also use `install.sh',
but that name is obsolete because some `make' programs have a rule
that creates `install' from it if there is no `Makefile'.

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

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

- Macro: AC_PROG_LEX
If `flex' is found, set output variable `LEX' to `flex' and
`LEXLIB' to `-lfl', if that library is in a standard place.
Otherwise set `LEX' to `lex' and `LEXLIB' to `-ll'.

Define `YYTEXT_POINTER' if `yytext' is a `char *' instead of a
`char []'. Also set output variable `LEX_OUTPUT_ROOT' to the base
of the file name that the lexer generates; usually `lex.yy', but
sometimes something else. These results vary according to whether
`lex' or `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 `yywrap' or, if you don't use it (e.g.,
your scanner has no `#include'-like feature), simply include a
`%noyywrap' statement in the scanner's source. Once this done,
the scanner is portable (unless _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:

AC_PROG_LEX
if test "$LEX" != flex; then
LEX="$SHELL $missing_dir/missing flex"
AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
AC_SUBST(LEXLIB, '')
fi

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

To ensure backward compatibility, Automake's `AM_PROG_LEX' invokes
(indirectly) this macro twice, which will cause an annoying but
benign "`AC_PROG_LEX' invoked multiple times" warning. Future
versions of Automake will fix this issue; meanwhile, just ignore
this message.

- Macro: AC_PROG_LN_S
If `ln -s' works on the current file system (the operating system
and file system support symbolic links), set the output variable
`LN_S' to `ln -s'; otherwise, if `ln' works, set `LN_S' to `ln',
and otherwise set it to `cp -p'.

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

In other words, it does not work to do:
$(LN_S) foo /x/bar

Instead, do:

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

- Macro: AC_PROG_RANLIB
Set output variable `RANLIB' to `ranlib' if `ranlib' is found, and
otherwise to `:' (do nothing).

- Macro: AC_PROG_YACC
If `bison' is found, set output variable `YACC' to `bison -y'.
Otherwise, if `byacc' is found, set `YACC' to `byacc'. Otherwise
set `YACC' to `yacc'.

File: autoconf.info, Node: Generic Programs, Prev: Particular Programs, Up: Alternative Programs

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
(*note Writing Tests::). By default, these macros use the environment
variable `PATH'. If you need to check for a program that might not be
in the user's `PATH', you can pass a modified path to use instead, like
this:

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

You are strongly encouraged to declare the VARIABLE passed to
`AC_CHECK_PROG' etc. as precious, *Note Setting Output Variables::,
`AC_ARG_VAR', for more details.

- Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND,
[VALUE-IF-NOT-FOUND], [PATH], [REJECT])
Check whether program PROG-TO-CHECK-FOR exists in `PATH'. If it
is found, set VARIABLE to VALUE-IF-FOUND, otherwise to
VALUE-IF-NOT-FOUND, if given. Always pass over REJECT (an
absolute file name) even if it is the first found in the search
path; in that case, set VARIABLE using the absolute file name of
the PROG-TO-CHECK-FOR found that is not REJECT. If VARIABLE was
already set, do nothing. Calls `AC_SUBST' for VARIABLE.

- Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR,
[VALUE-IF-NOT-FOUND], [PATH])
Check for each program in the whitespace-separated list
PROGS-TO-CHECK-FOR existing in the `PATH'. If one is found, set
VARIABLE to the name of that program. Otherwise, continue
checking the next program in the list. If none of the programs in
the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if
VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not
changed. Calls `AC_SUBST' for VARIABLE.

- Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR,
[VALUE-IF-NOT-FOUND], [PATH])
Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a
prefix of the host type as determined by `AC_CANONICAL_HOST',
followed by a dash (*note Canonicalizing::). For example, if the
user runs `configure --host=i386-gnu', then this call:
AC_CHECK_TOOL(RANLIB, ranlib, :)

sets `RANLIB' to `i386-gnu-ranlib' if that program exists in
`PATH', or otherwise to `ranlib' if that program exists in `PATH',
or to `:' if neither program exists.

- Macro: AC_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR,
[VALUE-IF-NOT-FOUND], [PATH])
Like `AC_CHECK_TOOL', each of the tools in the list
PROGS-TO-CHECK-FOR are checked with a prefix of the host type as
determined by `AC_CANONICAL_HOST', followed by a dash (*note
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 VARIABLE to the name of that program. If none of the
tools in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if
VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not
changed. Calls `AC_SUBST' for VARIABLE.

- Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR,
[VALUE-IF-NOT-FOUND], [PATH])
Like `AC_CHECK_PROG', but set VARIABLE to the entire path of
PROG-TO-CHECK-FOR if found.

- Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR,
[VALUE-IF-NOT-FOUND], [PATH])
Like `AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found,
set VARIABLE to the entire path of the program found.

- Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR,
[VALUE-IF-NOT-FOUND], [PATH])
Like `AC_CHECK_TOOL', but set VARIABLE to the entire path of the
program if it is found.

File: autoconf.info, Node: Files, Next: Libraries, Prev: Alternative Programs, Up: Existing Tests

Files
=====

You might also need to check for the existence of files. Before using
these macros, ask yourself whether a run-time 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.

- Macro: AC_CHECK_FILE (FILE, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
Check whether file FILE exists on the native system. If it is
found, execute ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND,
if given.

- Macro: AC_CHECK_FILES (FILES, [ACTION-IF-FOUND],
[ACTION-IF-NOT-FOUND])
Executes `AC_CHECK_FILE' once for each file listed in FILES.
Additionally, defines `HAVE_FILE' (*note Standard Symbols::) for
each file found.

File: autoconf.info, Node: Libraries, Next: Library Functions, Prev: Files, Up: Existing Tests

Library Files
=============

The following macros check for the presence of certain C, C++, or
Fortran library archive files.

- Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND],
[ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES])
Depending on the current language(*note Language Choice::), try to
ensure that the C, C++, or Fortran function FUNCTION is available
by checking whether a test program can be linked with the library
LIBRARY to get the function. LIBRARY is the base name of the
library; e.g., to check for `-lmp', use `mp' as the LIBRARY
argument.

ACTION-IF-FOUND is a list of shell commands to run if the link
with the library succeeds; ACTION-IF-NOT-FOUND is a list of shell
commands to run if the link fails. If ACTION-IF-FOUND is not
specified, the default action will prepend `-lLIBRARY' to `LIBS'
and define `HAVE_LIBLIBRARY' (in all capitals). This macro is
intended to support building `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. Some linkers are very sensitive to library ordering so the
order in which `LIBS' is generated is important to reliable
detection of libraries.

If linking with LIBRARY results in unresolved symbols that would
be resolved by linking with additional libraries, give those
libraries as the OTHER-LIBRARIES argument, separated by spaces:
e.g., `-lXt -lX11'. Otherwise, this macro will fail to detect
that LIBRARY is present, because linking the test program will
always fail with unresolved symbols. The 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 `LIBS'.

- Macro: AC_SEARCH_LIBS (FUNCTION, SEARCH-LIBS, [ACTION-IF-FOUND],
[ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES])
Search for a library defining FUNCTION if it's not already
available. This equates to calling
`AC_LINK_IFELSE([AC_LANG_CALL([], [FUNCTION])])' first with no
libraries, then for each library listed in SEARCH-LIBS.

Add `-lLIBRARY' to `LIBS' for the first library found to contain
FUNCTION, and run ACTION-IF-FOUND. If the function is not found,
run ACTION-IF-NOT-FOUND.

File: autoconf.info, Node: Library Functions, Next: Header Files, Prev: Libraries, Up: Existing Tests

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

File: autoconf.info, Node: Function Portability, Next: Particular Functions, Up: Library Functions

Portability of C Functions
--------------------------

Most usual functions can either be missing, or be buggy, or be limited
on some architectures. This section tries to make an inventory of these
portability issues. By definition, this list will always require
additions. Please help us keeping it as complete as possible.

`exit'
Did you know that, on some older hosts, `exit' returns `int'?
This is because `exit' predates `void', and there was a long
tradition of it returning `int'.

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

POSIX specifies that `putenv("FOO")' removes `FOO' from the
environment, but on some systems (eg. FreeBSD 4) this is not the
case and instead `unsetenv' must be used.

On MINGW, a call `putenv("FOO=")' removes `FOO' from the
environment, rather than inserting it with an empty value.

`signal' handler
Normally `signal' takes a handler function with a return type of
`void', but some old systems required `int' instead. Any actual
`int' value returned is not used, this is only a difference in the
function prototype demanded.

All systems we know of in current use take `void'. Presumably
`int' was to support K&R C, where of course `void' is not
available. `AC_TYPE_SIGNAL' (*note Particular Types::) can be
used to establish the correct type in all cases.

`snprintf'
The ISO C99 standard says that if the output array isn't big enough
and if no other errors occur, `snprintf' and `vsnprintf' truncate
the output and return the number of bytes that ought to have been
produced. Some 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).

`sprintf'
The ISO C standard says `sprintf' and `vsprintf' return the number
of bytes written, but on some old systems (SunOS 4 for instance)
they return the buffer pointer instead.

`sscanf'
On various old systems, e.g., HP-UX 9, `sscanf' requires that its
input string be writable (though it doesn't actually change it).
This can be a problem when using `gcc' since it normally puts
constant strings in read-only memory (*note Incompatibilities of
GCC: (gcc)Incompatibilities.). Apparently in some cases even
having format strings read-only can be a problem.

`strnlen'
AIX 4.3 provides a broken version which produces the following
results:

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

`sysconf'
`_SC_PAGESIZE'