This is Info file autoconf.info, produced by Makeinfo version 1.68 from
the input file autoconf.texi.

INFO-DIR-SECTION GNU admin
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 the conditionals in source code
* autoconf: (autoconf)autoconf Invocation.
                                How to create configuration scripts
* autoreconf: (autoconf)autoreconf Invocation.
                                Remaking multiple configure scripts
* configure: (autoconf)configure Invocation.
                                Configuring a package
* config.status: (autoconf)config.status Invocation.
                                Recreating a configuration
* testsuite: (autoconf)testsuite Invocation.
                                Running an Autotest test suite
END-INFO-DIR-ENTRY

   Autoconf: Creating Automatic Configuration Scripts, by David
MacKenzie.

   This file documents the GNU Autoconf package for creating scripts to
configure source code packages using templates and an `m4' macro
package.

   Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002
Free Software Foundation, Inc.

   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 no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".


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

Autoconf
********

   ifnottex

   This file documents the GNU Autoconf package for creating scripts to
configure source code packages using templates and the GNU M4 macro
package.  This is edition 2.53, for Autoconf version 2.53.

* 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
* Questions::                   Questions about Autoconf, 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 from 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

* 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
* C Compiler::                  Checking its characteristics
* C++ Compiler::                Likewise
* Fortran 77 Compiler::         Likewise

Writing Tests

* Examining Declarations::      Detecting header files and declarations
* Examining Syntax::            Detecting language syntax features
* Examining Libraries::         Detecting functions and global variables
* Run Time::                    Testing for run-time features
* Systemology::                 A zoology of operating systems
* Multiple Cases::              Tests for several possible values
* Language Choice::             Selecting which language to use for testing

Checking Run Time Behavior

* Test Programs::               Running test programs
* Guidelines::                  General rules for writing test programs
* Test Functions::              Avoiding pitfalls in test programs

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

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

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

Questions About Autoconf

* 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

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
Questions::, 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://sources.redhat.com/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 runtime information--but this is only one
piece of the puzzle for the development of portable software.  To this
end, the GNU project has developed a suite of integrated utilities to
finish the job Autoconf started: the GNU build system, whose most
important components are Autoconf, Automake, and Libtool.  In this
chapter, we introduce you to those tools, point you to sources of more
information, and try to convince you to use the entire GNU build system
for your software.

* Menu:

* Automake::                    Escaping Makefile hell
* 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').

   Automake may require that additional tools be present on the
*developer's* machine.  For example, the `Makefile.in' that the
developer works with may not be portable (e.g. it might use special
features of your compiler to automatically generate dependency
information).  Running `make dist', however, produces a
`hello-1.0.tar.gz' package (or whatever the program/version is) with a
`Makefile.in' that will work on any system.

   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 to 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, 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:

* 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


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

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

