path: root/util/autoconf/autoconf.info-1

This is Info file autoconf.info, produced by Makeinfo-1.55 from the
input file ./autoconf.texi.

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

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

   Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


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

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

* Menu:

* Introduction::                Autoconf's purpose, strengths, and weaknesses.
* 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.
* Writing Macros::              Adding new macros to Autoconf.
* Manual Configuration::        Selecting features that can't be guessed.
* Site Configuration::          Local defaults for `configure'.
* Invoking configure::          How to use the Autoconf output.
* Invoking config.status::      Recreating a configuration.
* Questions::                   Questions about Autoconf, with answers.
* Upgrading::                   Tips for upgrading from version 1.
* History::                     History of Autoconf.
* Old Macro Names::		Backward compatibility macros.
* Environment Variable Index::  Index of environment variables used.
* Output Variable Index::       Index of variables set in output files.
* Preprocessor Symbol Index::   Index of C preprocessor symbols defined.
* Macro Index::                 Index of Autoconf macros.

 -- The Detailed Node Listing --

Making `configure' Scripts

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

Initialization and Output Files

* Input::                       Where Autoconf should find files.
* Output::			Creating output files.
* Makefile Substitutions::      Using output variables in `Makefile's.
* Configuration Headers::       Creating a configuration header file.
* Subdirectories::              Configuring independent packages together.
* Default Prefix::              Changing the default installation prefix.
* Versions::                    Version numbers in `configure'.

Substitutions in Makefiles

* Preset Output Variables::	Output variables that are always set.
* Build Directories::		Compiling in a different directory.
* Automatic Remaking::		Makefile rules for configuring.

Configuration Header Files

* Header Templates::            Input for the configuration headers.
* Invoking autoheader::		How to create configuration templates.

Existing Tests

* Alternative Programs::	Selecting between alternative programs.
* Libraries::                   Library archives that might be missing.
* Library Functions::		C library functions that might be missing.
* Header Files::		Header files that might be missing.
* Structures::			Structures or members that might be missing.
* Typedefs::			`typedef's that might be missing.
* Compiler Characteristics::	C compiler or machine architecture features.
* System Services::		Operating system services.
* UNIX Variants::		Special kludges for specific UNIX variants.

Alternative Programs

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

Library 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.

Typedefs

* Particular Typedefs::         Special handling to find certain types.
* Generic Typedefs::            How to find other types.

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.
* Portable Shell::              Shell script portability pitfalls.
* Testing Values and Files::    Checking strings and files.
* 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 users of progress or problems.

Caching Results

* Cache Variable Names::        Shell variables used in caches.
* Cache Files::	        	Files `configure' uses for caching.

Writing Macros

* Macro Definitions::		Basic format of an Autoconf macro.
* Macro Names::                 What to call your new macros.
* Quoting::			Protecting macros from unwanted expansion.
* Dependencies Between Macros::	What to do when macros depend on other macros.

Dependencies Between Macros

* Prerequisite Macros::		Ensuring required information.
* Suggested Ordering::		Warning about possible ordering problems.
* Obsolete Macros::             Warning about old ways of doing things.

Manual Configuration

* Specifying Names::            Specifying the system type.
* Canonicalizing::              Getting the canonical system type.
* System Type Variables::       Variables containing the 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.
* 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 transforme 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.
* Build Directory::             Configuring in a different directory.
* 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'.
* Operation Controls::          Changing how `configure' runs.

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.

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.
* Invoking autoupdate::         Replacing old macro names in `configure.in'.
* Changed Results::             Changes in how to check test results.
* Changed Macro Writing::       Better ways to write your own macros.

History of Autoconf

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


File: autoconf.info,  Node: Introduction,  Next: Making configure Scripts,  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 electro-magnetic
     waves, the relativist 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 test for the presence of each
feature that the software package they are for might need individually.
(Before each check, they print a one-line message stating what they are
checking for, so the user doesn't get too bored while waiting for the
script to finish.)  As a result, they deal well with systems that are
hybrids or customized from the more common UNIX variants.  There is no
need to maintain files that list the features supported by each release
of each variant of UNIX.

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

   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.

   There are several jobs related to making portable software packages
that Autoconf currently does not do.  Among these are automatically
creating `Makefile' files with all of the standard targets, and
supplying replacements for standard library functions and header files
on systems that lack them.  Work is in progress to add those features in
the future.

   Autoconf imposes some restrictions on the names of macros used with
`#ifdef' 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' do not have.  It also
overflows internal limits of some versions of `m4', including GNU `m4'
1.0.  You must use version 1.1 or later of GNU `m4'.  Using version 1.3
or later will be much faster than 1.1 or 1.2.

   *Note Upgrading::, 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.

   Mail suggestions and bug reports for Autoconf to
`bug-gnu-utils@prep.ai.mit.edu'.  Please include the Autoconf version
number, which you can get by running `autoconf --version'.


File: autoconf.info,  Node: Making configure Scripts,  Next: Setup,  Prev: Introduction,  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 Invoking config.status::.);

   * a shell script called `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.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 write `acconfig.h', and you will distribute
the Autoconf-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.in
     
     configure.in --.   .------> autoconf* -----> configure
                    +---+
     [aclocal.m4] --+   `---.
     [acsite.m4] ---'       |
                            +--> [autoheader*] -> [config.h.in]
     [acconfig.h] ----.     |
                      +-----'
     [config.h.top] --+
     [config.h.bot] --'
     
     Makefile.in -------------------------------> Makefile.in

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.in::	What to put in an Autoconf input file.
* Invoking autoscan::           Semi-automatic `configure.in' writing.
* Invoking ifnames::            Listing the conditionals in source code.
* Invoking autoconf::		How to create configuration scripts.
* Invoking autoreconf::         Remaking multiple `configure' scripts.


File: autoconf.info,  Node: Writing configure.in,  Next: Invoking autoscan,  Up: Making configure Scripts

Writing `configure.in'
======================

   To produce a `configure' script for a software package, create a
file called `configure.in' that contains invocations of the Autoconf
macros that test the system features your package needs or can use.
Autoconf macros already exist to check for many features; see *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.in' might need to contain some
hand-crafted shell commands.  The `autoscan' program can give you a
good start in writing `configure.in' (*note Invoking autoscan::., for
more information).

   The order in which `configure.in' calls the Autoconf macros is not
important, with a few exceptions.  Every `configure.in' 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 creating `configure' 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 could depend on things earlier in it.  For example, library
functions could be affected by typedefs and libraries.

     `AC_INIT(FILE)'
     checks for programs
     checks for libraries
     checks for header files
     checks for typedefs
     checks for structures
     checks for compiler characteristics
     checks for library functions
     checks for system services
     `AC_OUTPUT([FILE...])'

   It is best to put each macro call on its own line in `configure.in'.
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.

   When calling macros that take arguments, there must not be any blank
space between the macro name and the open parenthesis.  Arguments can be
more than one line long if they are enclosed within the `m4' quote
characters `[' and `]'.  If you have a long line such as a list of file
names, you can generally use a backslash at the end of a line to
continue it logically on the next line (this is implemented by the
shell, not by anything special that Autoconf does).

   Some macros handle two cases: what to do if the given condition is
met, and what to do if the condition is not met.  In some places you
might want to do something if a condition is true but do nothing if it's
false, or vice versa.  To omit the true case, pass an empty value for
the ACTION-IF-FOUND argument to the macro.  To omit the false case,
omit the ACTION-IF-NOT-FOUND argument to the macro, including the comma
before it.

   You can include comments in `configure.in' files by starting them
with the `m4' builtin macro `dnl', which discards text up through the
next newline.  These comments do not appear in the generated
`configure' scripts.  For example, it is helpful to begin
`configure.in' files with a line like this:

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


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

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

   The `autoscan' program can help you create a `configure.in' 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.in' for that package.

   You should manually examine `configure.scan' before renaming it to
`configure.in'; 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_HEADER' (*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 Invoking ifnames::., for information about a program that can
help with that job).

   `autoscan' uses several data files, which are installed along with
the distributed Autoconf macro files, to determine which macros to
output when it finds particular symbols in a package's source files.
These files all have the same format.  Each line consists of a symbol,
whitespace, and the Autoconf macro to output if that symbol is
encountered.  Lines starting with `#' are comments.

   `autoscan' is only installed if you already have Perl installed.
`autoscan' accepts the following options:

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

`--macrodir=DIR'
     Look for the data files in directory DIR instead of the default
     installation directory.  You can also set the `AC_MACRODIR'
     environment variable to a directory; this option overrides the
     environment variable.

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

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


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

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

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

   `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.

`--macrodir=DIR'
`-m DIR'
     Look for the Autoconf macro files in directory DIR instead of the
     default installation directory.  Only used to get the version
     number.  You can also set the `AC_MACRODIR' environment variable
     to a directory; this option overrides the environment variable.

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


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

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

   To create `configure' from `configure.in', run the `autoconf'
program with no arguments.  `autoconf' processes `configure.in' with
the `m4' macro processor, using the Autoconf macros.  If you give
`autoconf' an argument, it reads that file instead of `configure.in'
and writes the configuration script to the standard output instead of
to `configure'.  If you give `autoconf' the argument `-', it reads the
standard input instead of `configure.in' and writes the configuration
script on the standard output.

   The Autoconf macros are defined in several files.  Some of the files
are distributed with Autoconf; `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
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.

`--localdir=DIR'
`-l DIR'
     Look for the package file `aclocal.m4' in directory DIR instead of
     in the current directory.

`--macrodir=DIR'
`-m DIR'
     Look for the installed macro files in directory DIR.  You can also
     set the `AC_MACRODIR' environment variable to a directory; this
     option overrides the environment variable.

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


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

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

   If you have a lot of Autoconf-generated `configure' scripts, the
`autoreconf' program can save you some work.  It runs `autoconf' (and
`autoheader', where appropriate) repeatedly to remake the Autoconf
`configure' scripts and configuration header templates in the directory
tree rooted at the current directory.  By default, it only remakes
those files that are older than their `configure.in' or (if present)
`aclocal.m4'.  Since `autoheader' does not change the timestamp of its
output file if the file wouldn't be changing, this is not necessarily
the minimum amount of work.  If you install a new version of Autoconf,
you can make `autoreconf' remake *all* of the files by giving it the
`--force' option.

   If you give `autoreconf' the `--macrodir=DIR' or `--localdir=DIR'
options, it passes them down to `autoconf' and `autoheader' (with
relative paths adjusted properly).

   *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 `--macrodir=DIR' or `--localdir=DIR'.

`autoreconf' accepts the following options:

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

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

`--localdir=DIR'
`-l DIR'
     Look for the package files `aclocal.m4' and `acconfig.h' (but not
     `FILE.top' and `FILE.bot') in directory DIR instead of in the
     directory containing each `configure.in'.

`--macrodir=DIR'
`-m DIR'
     Look for the Autoconf macro files in directory DIR instead of the
     default installation directory.  You can also set the `AC_MACRODIR'
     environment variable to a directory; this option overrides the
     environment variable.

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

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


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
initialization and creating output files.

* Menu:

* Input::                       Where Autoconf should find files.
* Output::			Creating output files.
* Makefile Substitutions::      Using output variables in `Makefile's.
* Configuration Headers::       Creating a configuration header file.
* Subdirectories::              Configuring independent packages together.
* Default Prefix::              Changing the default installation prefix.
* Versions::                    Version numbers in `configure'.


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

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

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

 - Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR)
     Process any command-line arguments and find the source code
     directory.  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 (*note Invoking configure::., 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 `install-sh', `config.sub', `config.guess', and Cygnus
     `configure' scripts 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' programs have a rule that
     creates `install' from it if there is no `Makefile'.


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

Creating Output Files
=====================

   Every Autoconf-generated `configure' script must finish by calling
`AC_OUTPUT'.  It is the macro that creates the `Makefile's and optional
other files resulting from configuration.  The only other required
macro is `AC_INIT' (*note Input::.).

 - Macro: AC_OUTPUT ([FILE...] [,EXTRA-CMDS] [,INIT-CMDS])
     Create output files.  The FILE... argument is a
     whitespace-separated list of output files; it may be empty.  This
     macro creates each file `FILE' by copying an input file (by default
     named `FILE.in'), substituting the output variable values.  *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 (but not the parents of that directory).
     Usually, `Makefile's are created this way, but other files, such
     as `.gdbinit', can be specified as well.

     If `AC_CONFIG_HEADER', `AC_LINK_FILES', or `AC_CONFIG_SUBDIRS' has
     been called, this macro also creates the files named as their
     arguments.

     A typical call to `AC_OUTPUT' looks like this:
          AC_OUTPUT(Makefile src/Makefile man/Makefile X/Imakefile)

     You can override an input file name by appending it to FILE,
     separated by a colon.  For example,
          AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk)

     If you pass EXTRA-CMDS, those commands will be inserted into
     `config.status' to be run after all its other processing.  If
     INIT-CMDS are given, they are inserted just before EXTRA-CMDS,
     with shell variable, command, and backslash substitutions
     performed on them in `configure'.  You can use INIT-CMDS to pass
     variables from `configure' to the EXTRA-CMDS.

   If you run `make' on 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 variable `MAKE', define output variable
     `SET_MAKE' to be empty.  Otherwise, define `SET_MAKE' to contain
     `MAKE=make'.  Calls `AC_SUBST' for `SET_MAKE'.

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

     @SET_MAKE@


File: autoconf.info,  Node: Makefile Substitutions,  Next: Configuration Headers,  Prev: Output,  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.info)Makefile Conventions,
for more information on what to put in `Makefile's.

* Menu:

* Preset Output Variables::	Output variables that are always set.
* Build Directories::		Compiling in a different directory.
* Automatic Remaking::		Makefile rules for configuring.


File: autoconf.info,  Node: Preset Output Variables,  Next: Build Directories,  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.  Here is what each of the preset ones
contains.

 - 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: exec_prefix
     The installation prefix for architecture-dependent files.

 - Variable: prefix
     The installation prefix for architecture-independent files.

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

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

 - 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: CPPFLAGS
     Header file search directory (`-IDIR') and any other miscellaneous
     options for the C preprocessor and compiler.  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 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_HEADER' 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: LDFLAGS
     Stripping (`-s') and any other miscellaneous options for the
     linker.  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 features.

 - Variable: LIBS
     `-l' and `-L' options to pass to the linker.


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

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

   You might want to compile a software package in a different directory
from the one that contains the source code.  Doing this allows you to
compile the package for several architectures simultaneously from the
same copy of the source code and keep multiple sets of object files on
disk.

   To support doing this, `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 in the correct value for `srcdir' when it
produces `Makefile.in'.

   Do not use the `make' variable `$<', which expands to the pathname
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 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.  On
some old BSD systems, `touch' or any command that results in an empty
file does not update the timestamps, so use a command like `date' as a
workaround.

     ${srcdir}/configure: configure.in 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.in aclocal.m4 acconfig.h \
         config.h.top config.h.bot
             cd ${srcdir} && autoheader
             date > ${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

   In addition, you should pass `date > stamp-h' in the EXTRA-CMDS
argument to `AC_OUTPUT', so `config.status' will ensure that `config.h'
is considered up to date.  *Note Output::, for more information about
`AC_OUTPUT'.

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


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

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

   When a package tests more than a few 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_HEADER'
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_HEADER (HEADER-TO-CREATE ...)
     Make `AC_OUTPUT' create the file(s) in the whitespace-separated
     list HEADER-TO-CREATE 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-TO-CREATE is `config.h'.

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

     Usually the input file is named `HEADER-TO-CREATE.in'; however,
     you can override the input file name by appending it to
     HEADER-TO-CREATE, separated by a colon.  For example,
          AC_CONFIG_HEADER(defines.h:defines.hin)

     Doing this allows you to keep your filenames acceptable to MS-DOS.

* Menu:

* Header Templates::            Input for the configuration headers.
* Invoking autoheader::		How to create configuration templates.


File: autoconf.info,  Node: Header Templates,  Next: Invoking autoheader,  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 default
values in the `#define' statements.  For example, suppose your
`configure.in' makes these calls:

     AC_CONFIG_HEADER(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 change the 0 to a 1.  On other
systems, it will leave the line unchanged.

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

   Alternately, if your code tests for configuration options using
`#ifdef' instead of `#if', a default value can be to `#undef' the
variable instead of to define it to a value.  On systems that have
`unistd.h', `configure' will change the second line to read `#define
HAVE_UNISTD_H 1'.  On other systems, it will comment that line out (in
case the system predefines that symbol).

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


File: autoconf.info,  Node: Invoking autoheader,  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.in' invokes
`AC_CONFIG_HEADER(FILE)', `autoheader' creates `FILE.in'.  Otherwise,
`autoheader' creates `config.h.in'.

   If you give `autoheader' an argument, it uses that file instead of
`configure.in' 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.in' and writes
the header file to the standard output.

   `autoheader' scans `configure.in' and figures out which C
preprocessor symbols it might define.  It copies comments and `#define'
and `#undef' statements from a file called `acconfig.h', which comes
with and is installed with Autoconf.  It also uses a file called
`acconfig.h' in the current directory, if present.  If you `AC_DEFINE'
any additional symbols, you must create that file with entries for
them.  For symbols defined by `AC_CHECK_HEADERS', `AC_CHECK_FUNCS',
`AC_CHECK_SIZEOF', or `AC_CHECK_LIB', `autoheader' generates comments
and `#undef' statements itself rather than copying them from a file,
since the possible symbols are effectively limitless.

   The file that `autoheader' creates contains mainly `#define' and
`#undef' statements and their accompanying comments.  If `./acconfig.h'
contains the string `@TOP@', `autoheader' copies the lines before the
line containing `@TOP@' into the top of the file that it generates.
Similarly, if `./acconfig.h' contains the string `@BOTTOM@',
`autoheader' copies the lines after that line to the end of the file it
generates.  Either or both of those strings may be omitted.

   An alternate way to produce the same effect is to create the files
`FILE.top' (typically `config.h.top') and/or `FILE.bot' in the current
directory.  If they exist, `autoheader' copies them to the beginning
and end, respectively, of its output.  Their use is discouraged because
they have file names that contain two periods, and so can not be stored
on MS-DOS; also, they are two more files to clutter up the directory.
But if you use the `--localdir=DIR' option to use an `acconfig.h' in
another directory, they give you a way to put custom boilerplate in each
individual `config.h.in'.

   `autoheader' accepts the following options:

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

`--localdir=DIR'
`-l DIR'
     Look for the package files `aclocal.m4' and `acconfig.h' (but not
     `FILE.top' and `FILE.bot') in directory DIR instead of in the
     current directory.

`--macrodir=DIR'
`-m DIR'
     Look for the installed macro files and `acconfig.h' in directory
     DIR.  You can also set the `AC_MACRODIR' environment variable to a
     directory; this option overrides the environment variable.

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


File: autoconf.info,  Node: Subdirectories,  Next: Default Prefix,  Prev: Configuration Headers,  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.  If a given DIR is not found, no
     error is reported, so a `configure' script can configure whichever
     parts of a large source tree are present.  If a given DIR contains
     `configure.in' but no `configure', the Cygnus `configure' script
     found by `AC_CONFIG_AUXDIR' 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 (e.g., to
     adjust a relative path for the cache file or source directory).
     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.


File: autoconf.info,  Node: Default Prefix,  Next: Versions,  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 besides
`/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;
     otherwise leave the prefix specified in `Makefile.in' unchanged.
     For example, if PROGRAM is `gcc' and the `PATH' contains
     `/usr/local/gnu/bin/gcc', set the prefix to `/usr/local/gnu'.