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

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: Transforming Names,  Next: Site Defaults,  Prev: Site Details,  Up: Site Configuration

Transforming Program Names When Installing
==========================================

   Autoconf supports changing the names of programs when installing
them.  In order to use these transformations, `configure.in' must call
the macro `AC_ARG_PROGRAM'.

 - Macro: AC_ARG_PROGRAM
     Place in output variable `program_transform_name' a sequence of
     `sed' commands for changing the names of installed programs.

     If any of the options described below are given to `configure',
     program names are transformed accordingly.  Otherwise, if
     `AC_CANONICAL_SYSTEM' has been called and a `--target' value is
     given that differs from the host type (specified with `--host' or
     defaulted by `config.sub'), the target type followed by a dash is
     used as a prefix.  Otherwise, no program name transformation is
     done.

* Menu:

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


File: autoconf.info,  Node: Transformation Options,  Next: Transformation Examples,  Up: Transforming Names

Transformation Options
----------------------

   You can specify name transformations by giving `configure' these
command line options:

`--program-prefix=PREFIX'
     prepend PREFIX to the names;

`--program-suffix=SUFFIX'
     append SUFFIX to the names;

`--program-transform-name=EXPRESSION'
     perform `sed' substitution EXPRESSION on the names.


File: autoconf.info,  Node: Transformation Examples,  Next: Transformation Rules,  Prev: Transformation Options,  Up: Transforming Names

Transformation Examples
-----------------------

   These transformations are useful with programs that can be part of a
cross-compilation development environment.  For example, a
cross-assembler running on a Sun 4 configured with
`--target=i960-vxworks' is normally installed as `i960-vxworks-as',
rather than `as', which could be confused with a native Sun 4 assembler.

   You can force a program name to begin with `g', if you don't want
GNU programs installed on your system to shadow other programs with the
same name.  For example, if you configure GNU `diff' with
`--program-prefix=g', then when you run `make install' it is installed
as `/usr/local/bin/gdiff'.

   As a more sophistocated example, you could use
     --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'

to prepend `g' to most of the program names in a source tree, excepting
those like `gdb' that already have one and those like `less' and
`lesskey' that aren't GNU programs.  (That is assuming that you have a
source tree containing those programs that is set up to use this
feature.)

   One way to install multiple versions of some programs simultaneously
is to append a version number to the name of one or both.  For example,
if you want to keep Autoconf version 1 around for awhile, you can
configure Autoconf version 2 using `--program-suffix=2' to install the
programs as `/usr/local/bin/autoconf2', `/usr/local/bin/autoheader2',
etc.


File: autoconf.info,  Node: Transformation Rules,  Prev: Transformation Examples,  Up: Transforming Names

Transformation Rules
--------------------

   Here is how to use the variable `program_transform_name' in a
`Makefile.in':

     transform=@program_transform_name@
     install: all
             $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog|sed '$(transform)'`
     
     uninstall:
             rm -f $(bindir)/`echo myprog|sed '$(transform)'`

If you have more than one program to install, you can do it in a loop:

     PROGRAMS=cp ls rm
     install:
             for p in $(PROGRAMS); do \
               $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p|sed '$(transform)'`; \
             done
     
     uninstall:
             for p in $(PROGRAMS); do \
               rm -f $(bindir)/`echo $$p|sed '$(transform)'`; \
             done

   Whether to do the transformations on documentation files (Texinfo or
`man') is a tricky question; there seems to be no perfect answer, due
to the several reasons for name transforming.  Documentation is not
usually particular to a specific architecture, and Texinfo files do not
conflict with system documentation.  But they might conflict with
earlier versions of the same files, and `man' pages sometimes do
conflict with system documentation.  As a compromise, it is probably
best to do name transformations on `man' pages but not on Texinfo
manuals.


File: autoconf.info,  Node: Site Defaults,  Prev: Transforming Names,  Up: Site Configuration

Setting Site Defaults
=====================

   Autoconf-generated `configure' scripts allow your site to provide
default values for some configuration values.  You do this by creating
site- and system-wide initialization files.

   If the environment variable `CONFIG_SITE' is set, `configure' uses
its value as the name of a shell script to read.  Otherwise, it reads
the shell script `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Thus, settings in
machine-specific files override those in machine-independent ones in
case of conflict.

   Site files can be arbitrary shell scripts, but only certain kinds of
code are really appropriate to be in them.  Because `configure' reads
any cache file after it has read any site files, a site file can define
a default cache file to be shared between all Autoconf-generated
`configure' scripts run on that system.  If you set a default cache
file in a site file, it is a good idea to also set the output variable
`CC' in that site file, because the cache file is only valid for a
particular compiler, but many systems have several available.

   Site files are also good places to set default values for other
output variables, such as `CFLAGS', if you need to give them non-default
values: anything you would normally do, repetitively, on the command
line.  If you use non-default values for PREFIX or EXEC_PREFIX
(wherever you locate the site file), you can set them in the site file
if you specify it with the `CONFIG_SITE' environment variable.

   You can set some cache values in the site file itself.  Doing this is
useful if you are cross-compiling, so it is impossible to check features
that require running a test program.  You could "prime the cache" by
setting those values correctly for that system in
`PREFIX/etc/config.site'.  To find out the names of the cache variables
you need to set, look for shell variables with `_cv_' in their names in
the affected `configure' scripts, or in the Autoconf `m4' source code
for those macros.

   The cache file is careful to not override any variables set in the
site files.  Similarly, you should not override command-line options in
the site files.  Your code should check that variables such as `prefix'
and `cache_file' have their default values (as set near the top of
`configure') before changing them.

   Here is a sample file `/usr/share/local/gnu/share/config.site'.  The
command `configure --prefix=/usr/share/local/gnu' would read this file
(if `CONFIG_SITE' is not set to a different file).

     # config.site for configure
     #
     # Default --prefix and --exec-prefix.
     test "$prefix" = NONE && prefix=/usr/share/local/gnu
     test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
     #
     # Give Autoconf 2.x generated configure scripts a shared default
     # cache file for feature test results, architecture-specific.
     if test "$cache_file" = ./config.cache; then
       cache_file="$prefix/var/config.cache"
       # A cache file is only valid for one C compiler.
       CC=gcc
     fi


File: autoconf.info,  Node: Invoking configure,  Next: Invoking config.status,  Prev: Site Configuration,  Up: Top

Running `configure' Scripts
***************************

   Below are instructions on how to configure a package that uses a
`configure' script, suitable for inclusion as an `INSTALL' file in the
package.  A plain-text version of `INSTALL' which you may use comes
with Autoconf.

* Menu:

* Basic Installation::          Instructions for typical cases.
* Compilers and Options::       Selecting compilers and optimization.
* Build Directory::             Configuring in a different directory.
* Installation Names::          Installing in different directories.
* 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.


File: autoconf.info,  Node: Basic Installation,  Next: Compilers and Options,  Up: Invoking configure

Basic Installation
==================

   These are generic installation instructions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a file
`config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.

   The file `configure.in' is used to create `configure' by a program
called `autoconf'.  You only need `configure.in' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source directory by typing `make clean'.  To also remove the files
     that `configure' created (so you can compile the package for a
     different kind of computer), type `make distclean'.


File: autoconf.info,  Node: Compilers and Options,  Next: Build Directory,  Prev: Basic Installation,  Up: Invoking configure

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:
     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

Or on systems that have the `env' program, you can do it like this:
     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure


File: autoconf.info,  Node: Build Directory,  Next: Installation Names,  Prev: Compilers and Options,  Up: Invoking configure

Using a Different Build Directory
=================================

   You can compile the package in a different directory from the one
containing the source code.  Doing so allows you to compile it on more
than one kind of computer at the same time.  To do this, you must use a
version of `make' that supports the `VPATH' variable, such as GNU
`make'.  `cd' to the directory where you want the object files and
executables to go and run the `configure' script.  `configure'
automatically checks for the source code in the directory that
`configure' is in and in `..'.


File: autoconf.info,  Node: Installation Names,  Next: Optional Features,  Prev: Build Directory,  Up: Invoking configure

Installation Names
==================

   By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.


File: autoconf.info,  Node: Optional Features,  Next: System Type,  Prev: Installation Names,  Up: Invoking configure

Optional Features
=================

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.


File: autoconf.info,  Node: System Type,  Next: Sharing Defaults,  Prev: Optional Features,  Up: Invoking configure

Specifying the System Type
==========================

   There may be some features `configure' can not figure out
automatically, but needs to determine by the type of host the package
will run on.  Usually `configure' can figure that out, but if it prints
a message saying it can not guess the host type, give it the
`--host=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:
     CPU-COMPANY-SYSTEM

See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the host type.

   If you are building compiler tools for cross-compiling, you can also
use the `--target=TYPE' option to select the type of system they will
produce code for and the `--build=TYPE' option to select the type of
system on which you are compiling the package.


File: autoconf.info,  Node: Sharing Defaults,  Next: Operation Controls,  Prev: System Type,  Up: Invoking configure

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.


File: autoconf.info,  Node: Operation Controls,  Prev: Sharing Defaults,  Up: Invoking configure

Operation Controls
==================

   `configure' recognizes the following options to control how it
operates.

`--cache-file=FILE'
     Save the results of the tests in FILE instead of `config.cache'.
     Set FILE to `/dev/null' to disable caching, for debugging
     `configure'.

`--help'
     Print a summary of the options to `configure', and exit.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--version'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`configure' also accepts some other, not widely useful, options.


File: autoconf.info,  Node: Invoking config.status,  Next: Questions,  Prev: Invoking configure,  Up: Top

Recreating a Configuration
**************************

   The `configure' script creates a file named `config.status' which
describes which configuration options were specified when the package
was last configured.  This file is a shell script which, if run, will
recreate the same configuration.

   You can give `config.status' the `--recheck' option to update
itself.  This option is useful if you change `configure', so that the
results of some tests might be different from the previous run.  The
`--recheck' option re-runs `configure' with the same arguments you used
before, plus the `--no-create' option, which prevent `configure' from
running `config.status' and creating `Makefile' and other files, and
the `--no-recursion' option, which prevents `configure' from running
other `configure' scripts in subdirectories.  (This is so other
`Makefile' rules can run `config.status' when it changes; *note
Automatic Remaking::., for an example).

   `config.status' also accepts the options `--help', which prints a
summary of the options to `config.status', and `--version', which
prints the version of Autoconf used to create the `configure' script
that generated `config.status'.

   `config.status' checks several optional environment variables that
can alter its behavior:

 - Variable: CONFIG_SHELL
     The shell with which to run `configure' for the `--recheck'
     option.  It must be Bourne-compatible.  The default is `/bin/sh'.

 - Variable: CONFIG_STATUS
     The file name to use for the shell script that records the
     configuration.  The default is `./config.status'.  This variable is
     useful when one package uses parts of another and the `configure'
     scripts shouldn't be merged because they are maintained separately.

   The following variables provide one way for separately distributed
packages to share the values computed by `configure'.  Doing so can be
useful if some of the packages need a superset of the features that one
of them, perhaps a common library, does.  These variables allow a
`config.status' file to create files other than the ones that its
`configure.in' specifies, so it can be used for a different package.

 - Variable: CONFIG_FILES
     The files in which to perform `@VARIABLE@' substitutions.  The
     default is the arguments given to `AC_OUTPUT' in `configure.in'.

 - Variable: CONFIG_HEADERS
     The files in which to substitute C `#define' statements.  The
     default is the arguments given to `AC_CONFIG_HEADER'; if that
     macro was not called, `config.status' ignores this variable.

   These variables also allow you to write `Makefile' rules that
regenerate only some of the files.  For example, in the dependencies
given above (*note Automatic Remaking::.), `config.status' is run twice
when `configure.in' has changed.  If that bothers you, you can make
each run only regenerate the files for that rule:

     config.h: stamp-h
     stamp-h: config.h.in config.status
             CONFIG_FILES= CONFIG_HEADERS=config.h ./config.status
             echo > stamp-h
     
     Makefile: Makefile.in config.status
             CONFIG_FILES=Makefile CONFIG_HEADERS= ./config.status

(If `configure.in' does not call `AC_CONFIG_HEADER', there is no need
to set `CONFIG_HEADERS' in the `make' rules.)


File: autoconf.info,  Node: Questions,  Next: Upgrading,  Prev: Invoking config.status,  Up: Top

Questions About Autoconf
************************

   Several questions about Autoconf come up occasionally.  Here some of
them are addressed.

* Menu:

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


File: autoconf.info,  Node: Distributing,  Next: Why GNU m4,  Up: Questions

Distributing `configure' Scripts
================================

     What are the restrictions on distributing `configure'
     scripts that Autoconf generates?  How does that affect my
     programs that use them?

   There are no restrictions on how the configuration scripts that
Autoconf produces may be distributed or used.  In Autoconf version 1,
they were covered by the GNU General Public License.  We still
encourage software authors to distribute their work under terms like
those of the GPL, but doing so is not required to use Autoconf.

   Of the other files that might be used with `configure',
`config.h.in' is under whatever copyright you use for your
`configure.in', since it is derived from that file and from the public
domain file `acconfig.h'.  `config.sub' and `config.guess' have an
exception to the GPL when they are used with an Autoconf-generated
`configure' script, which permits you to distribute them under the same
terms as the rest of your package.  `install-sh' is from the X
Consortium and is not copyrighted.


File: autoconf.info,  Node: Why GNU m4,  Next: Bootstrapping,  Prev: Distributing,  Up: Questions

Why Require GNU `m4'?
=====================

     Why does Autoconf require GNU `m4'?

   Many `m4' implementations have hard-coded limitations on the size
and number of macros, which Autoconf exceeds.  They also lack several
builtin macros that it would be difficult to get along without in a
sophisticated application like Autoconf, including:

     builtin
     indir
     patsubst
     __file__
     __line__

   Since only software maintainers need to use Autoconf, and since GNU
`m4' is simple to configure and install, it seems reasonable to require
GNU `m4' to be installed also.  Many maintainers of GNU and other free
software already have most of the GNU utilities installed, since they
prefer them.


File: autoconf.info,  Node: Bootstrapping,  Next: Why Not Imake,  Prev: Why GNU m4,  Up: Questions

How Can I Bootstrap?
====================

     If Autoconf requires GNU `m4' and GNU `m4' has an
     Autoconf `configure' script, how do I bootstrap?  It seems
     like a chicken and egg problem!

   This is a misunderstanding.  Although GNU `m4' does come with a
`configure' script produced by Autoconf, Autoconf is not required in
order to run the script and install GNU `m4'.  Autoconf is only
required if you want to change the `m4' `configure' script, which few
people have to do (mainly its maintainer).


File: autoconf.info,  Node: Why Not Imake,  Prev: Bootstrapping,  Up: Questions

Why Not Imake?
==============

     Why not use Imake instead of `configure' scripts?

   Several people have written addressing this question, so I include
adaptations of their explanations here.

   The following answer is based on one written by Richard Pixley:

   Autoconf generated scripts frequently work on machines which it has
never been set up to handle before.  That is, it does a good job of
inferring a configuration for a new system.  Imake cannot do this.

   Imake uses a common database of host specific data.  For X11, this
makes sense because the distribution is made as a collection of tools,
by one central authority who has control over the database.

   GNU tools are not released this way.  Each GNU tool has a maintainer;
these maintainers are scattered across the world.  Using a common
database would be a maintenance nightmare.  Autoconf may appear to be
this kind of database, but in fact it is not.  Instead of listing host
dependencies, it lists program requirements.

   Imake is special-purpose.  It is directed at building the X11
distribution.  By comparison to the GNU tools, this is a simple problem.
If you view the GNU suite as a collection of native tools, then the
problems are similar.  But the GNU tools are more powerful than that.
The development tools can be configured as cross tools in almost any
host+target permutation.  All of these configurations can be installed
concurrently.  They can even be configured to share host independent
files across hosts.  Imake doesn't address these issues.

   Imake templates are a form of standardization.  The GNU coding
standards address the same issues without necessarily imposing the same
restrictions.

   Here is some further explanation, written by Per Bothner:

   One of the advantages of Imake is that it easy to generate large
Makefiles using `cpp''s `#include' and macro mechanisms.  However,
`cpp' is not programmable: it has limited conditional facilities, and
no looping.  And `cpp' cannot inspect its environment.

   All of these problems are solved by using `sh' instead of `cpp'.
The shell is fully programmable, has macro substitution, can execute
(or source) other shell scripts, and can inspect its environment.

   Paul Eggert elaborates more:

   With Autoconf, installers need not assume that Imake itself is
already installed and working well.  This may not seem like much of an
advantage to people who are accustomed to Imake.  But on many hosts
Imake is not installed or the default installation is not working well,
and requiring Imake to install a package hinders the acceptance of that
package on those hosts.  For example, the Imake template and
configuration files might not be installed properly on a host, or the
Imake build procedure might wrongly assume that all source files are in
one big directory tree, or the Imake configuration might assume one
compiler whereas the package or the installer needs to use another, or
there might be a version mismatch between the Imake expected by the
package and the Imake suported by the host.  These problems are much
rarer with Autoconf, where each package comes with its own independent
configuration processor.

   Also, Imake often suffers from unexpected interactions between
`make' and the installer's C preprocessor.  The fundamental problem
here is that the C preprocessor was designed to preprocess C programs,
not `Makefile's.  This is much less of a problem with Autoconf, which
uses the general-purpose preprocessor `m4', and where the package's
author (rather than the installer) does the preprocessing in a standard
way.

   Finally, Mark Eichin notes:

   Imake isn't all that extensible, either.  In order to add new
features to Imake, you need to provide you own project template, and
duplicate most of the features of the existing one.  This means that
for a sophisticated project, using the vendor-provided Imake templates
fails to provide any leverage--since they don't cover anything that
your own project needs (unless it is an X11 program).

   On the other side, though:

   The one advantage that Imake has over `configure': `Imakefile's tend
to be much shorter (likewise, less redundant) than `Makefile.in's.
There is a fix to this, however--at least for the Kerberos V5 tree,
we've modified things to call in common `post.in' and `pre.in'
`Makefile' fragments for the entire tree.  This means that a lot of
common things don't have to be duplicated, even though they normally
are in `configure' setups.


File: autoconf.info,  Node: Upgrading,  Next: History,  Prev: Questions,  Up: Top

Upgrading From Version 1
************************

   Autoconf version 2 is mostly backward compatible with version 1.
However, it introduces better ways to do some things, and doesn't
support some of the ugly things in version 1.  So, depending on how
sophisticated your `configure.in' files are, you might have to do some
manual work in order to upgrade to version 2.  This chapter points out
some problems to watch for when upgrading.  Also, perhaps your
`configure' scripts could benefit from some of the new features in
version 2; the changes are summarized in the file `NEWS' in the
Autoconf distribution.

   First, make sure you have GNU `m4' version 1.1 or higher installed,
preferably 1.3 or higher.  Versions before 1.1 have bugs that prevent
them from working with Autoconf version 2.  Versions 1.3 and later are
much faster than earlier versions, because as of version 1.3, GNU `m4'
has a more efficient implementation of diversions and can freeze its
internal state in a file that it can read back quickly.

* Menu:

* Changed File Names::          Files you might rename.
* Changed Makefiles::           New things to put in `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.


File: autoconf.info,  Node: Changed File Names,  Next: Changed Makefiles,  Up: Upgrading

Changed File Names
==================

   If you have an `aclocal.m4' installed with Autoconf (as opposed to
in a particular package's source directory), you must rename it to
`acsite.m4'.  *Note Invoking autoconf::.

   If you distribute `install.sh' with your package, rename it to
`install-sh' so `make' builtin rules won't inadvertantly create a file
called `install' from it.  `AC_PROG_INSTALL' looks for the script under
both names, but it is best to use the new name.

   If you were using `config.h.top' or `config.h.bot', you still can,
but you will have less clutter if you merge them into `acconfig.h'.
*Note Invoking autoheader::.


File: autoconf.info,  Node: Changed Makefiles,  Next: Changed Macros,  Prev: Changed File Names,  Up: Upgrading

Changed Makefiles
=================

   Add `@CFLAGS@', `@CPPFLAGS@', and `@LDFLAGS@' in your `Makefile.in'
files, so they can take advantage of the values of those variables in
the environment when `configure' is run.  Doing this isn't necessary,
but it's a convenience for users.

   Also add `@configure_input@' in a comment to each input file for
`AC_OUTPUT', so that the output files will contain a comment saying
they were produced by `configure'.  Automatically selecting the right
comment syntax for all the kinds of files that people call `AC_OUTPUT'
on became too much work.

   Add `config.log' and `config.cache' to the list of files you remove
in `distclean' targets.

   If you have the following in `Makefile.in':

     prefix = /usr/local
     exec_prefix = ${prefix}

you must change it to:

     prefix = @prefix@
     exec_prefix = @exec_prefix@

The old feature of replacing those variables without `@' characters
around them has been removed.


File: autoconf.info,  Node: Changed Macros,  Next: Invoking autoupdate,  Prev: Changed Makefiles,  Up: Upgrading

Changed Macros
==============

   Many of the macros were renamed in Autoconf version 2.  You can still
use the old names, but the new ones are clearer, and it's easier to find
the documentation for them.  *Note Old Macro Names::, for a table
showing the new names for the old macros.  Use the `autoupdate' program
to convert your `configure.in' to using the new macro names.  *Note
Invoking autoupdate::.

   Some macros have been superseded by similar ones that do the job
better, but are not call-compatible.  If you get warnings about calling
obsolete macros while running `autoconf', you may safely ignore them,
but your `configure' script will generally work better if you follow
the advice it prints about what to replace the obsolete macros with.  In
particular, the mechanism for reporting the results of tests has
changed.  If you were using `echo' or `AC_VERBOSE' (perhaps via
`AC_COMPILE_CHECK'), your `configure' script's output will look better
if you switch to `AC_MSG_CHECKING' and `AC_MSG_RESULT'.  *Note Printing
Messages::.  Those macros work best in conjunction with cache
variables.  *Note Caching Results::.


File: autoconf.info,  Node: Invoking autoupdate,  Next: Changed Results,  Prev: Changed Macros,  Up: Upgrading

Using `autoupdate' to Modernize `configure'
===========================================

   The `autoupdate' program updates a `configure.in' file that calls
Autoconf macros by their old names to use the current macro names.  In
version 2 of Autoconf, most of the macros were renamed to use a more
uniform and descriptive naming scheme.  *Note Macro Names::, for a
description of the new scheme.  Although the old names still work
(*note Old Macro Names::., for a list of the old macro names and the
corresponding new names), you can make your `configure.in' files more
readable and make it easier to use the current Autoconf documentation
if you update them to use the new macro names.

   If given no arguments, `autoupdate' updates `configure.in', backing
up the original version with the suffix `~' (or the value of the
environment variable `SIMPLE_BACKUP_SUFFIX', if that is set).  If you
give `autoupdate' an argument, it reads that file instead of
`configure.in' and writes the updated file to the standard output.

`autoupdate' 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.  You can also set the `AC_MACRODIR'
     environment variable to a directory; this option overrides the
     environment variable.

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


File: autoconf.info,  Node: Changed Results,  Next: Changed Macro Writing,  Prev: Invoking autoupdate,  Up: Upgrading

Changed Results
===============

   If you were checking the results of previous tests by examining the
shell variable `DEFS', you need to switch to checking the values of the
cache variables for those tests.  `DEFS' no longer exists while
`configure' is running; it is only created when generating output
files.  This difference from version 1 is because properly quoting the
contents of that variable turned out to be too cumbersome and
inefficient to do every time `AC_DEFINE' is called.  *Note Cache
Variable Names::.

   For example, here is a `configure.in' fragment written for Autoconf
version 1:

     AC_HAVE_FUNCS(syslog)
     case "$DEFS" in
     *-DHAVE_SYSLOG*) ;;
     *) # syslog is not in the default libraries.  See if it's in some other.
       saved_LIBS="$LIBS"
       for lib in bsd socket inet; do
         AC_CHECKING(for syslog in -l$lib)
         LIBS="$saved_LIBS -l$lib"
         AC_HAVE_FUNCS(syslog)
         case "$DEFS" in
         *-DHAVE_SYSLOG*) break ;;
         *) ;;
         esac
         LIBS="$saved_LIBS"
       done ;;
     esac

   Here is a way to write it for version 2:

     AC_CHECK_FUNCS(syslog)
     if test $ac_cv_func_syslog = no; then
       # syslog is not in the default libraries.  See if it's in some other.
       for lib in bsd socket inet; do
         AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
           LIBS="$LIBS $lib"; break])
       done
     fi

   If you were working around bugs in `AC_DEFINE_UNQUOTED' by adding
backslashes before quotes, you need to remove them.  It now works
predictably, and does not treat quotes (except backquotes) specially.
*Note Setting Output Variables::.

   All of the boolean shell variables set by Autoconf macros now use
`yes' for the true value.  Most of them use `no' for false, though for
backward compatibility some use the empty string instead.  If you were
relying on a shell variable being set to something like 1 or `t' for
true, you need to change your tests.


File: autoconf.info,  Node: Changed Macro Writing,  Prev: Changed Results,  Up: Upgrading

Changed Macro Writing
=====================

   When defining your own macros, you should now use `AC_DEFUN' instead
of `define'.  `AC_DEFUN' automatically calls `AC_PROVIDE' and ensures
that macros called via `AC_REQUIRE' do not interrupt other macros, to
prevent nested `checking...' messages on the screen.  There's no actual
harm in continuing to use the older way, but it's less convenient and
attractive.  *Note Macro Definitions::.

   You probably looked at the macros that came with Autoconf as a guide
for how to do things.  It would be a good idea to take a look at the new
versions of them, as the style is somewhat improved and they take
advantage of some new features.

   If you were doing tricky things with undocumented Autoconf internals
(macros, variables, diversions), check whether you need to change
anything to account for changes that have been made.  Perhaps you can
even use an officially supported technique in version 2 instead of
kludging.  Or perhaps not.

   To speed up your locally written feature tests, add caching to them.
See whether any of your tests are of general enough usefulness to
encapsulate into macros that you can share.


File: autoconf.info,  Node: History,  Next: Old Macro Names,  Prev: Upgrading,  Up: Top

History of Autoconf
*******************

   You may be wondering, Why was Autoconf originally written?  How did
it get into its present form?  (Why does it look like gorilla spit?)  If
you're not wondering, then this chapter contains no information useful
to you, and you might as well skip it.  If you *are* wondering, then
let there be light...

* Menu:

* 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: Genesis,  Next: Exodus,  Up: History

Genesis
=======

   In June 1991 I was maintaining many of the GNU utilities for the Free
Software Foundation.  As they were ported to more platforms and more
programs were added, the number of `-D' options that users had to
select in the `Makefile' (around 20) became burdensome.  Especially for
me--I had to test each new release on a bunch of different systems.  So
I wrote a little shell script to guess some of the correct settings for
the fileutils package, and released it as part of fileutils 2.0.  That
`configure' script worked well enough that the next month I adapted it
(by hand) to create similar `configure' scripts for several other GNU
utilities packages.  Brian Berliner also adapted one of my scripts for
his CVS revision control system.

   Later that summer, I learned that Richard Stallman and Richard Pixley
were developing similar scripts to use in the GNU compiler tools; so I
adapted my `configure' scripts to support their evolving interface:
using the file name `Makefile.in' as the templates; adding `+srcdir',
the first option (of many); and creating `config.status' files.


File: autoconf.info,  Node: Exodus,  Next: Leviticus,  Prev: Genesis,  Up: History

Exodus
======

   As I got feedback from users, I incorporated many improvements, using
Emacs to search and replace, cut and paste, similar changes in each of
the scripts.  As I adapted more GNU utilities packages to use
`configure' scripts, updating them all by hand became impractical.
Rich Murphey, the maintainer of the GNU graphics utilities, sent me mail
saying that the `configure' scripts were great, and asking if I had a
tool for generating them that I could send him.  No, I thought, but I
should!  So I started to work out how to generate them.  And the
journey from the slavery of hand-written `configure' scripts to the
abundance and ease of Autoconf began.

   Cygnus `configure', which was being developed at around that time,
is table driven; it is meant to deal mainly with a discrete number of
system types with a small number of mainly unguessable features (such as
details of the object file format).  The automatic configuration system
that Brian Fox had developed for Bash takes a similar approach.  For
general use, it seems to me a hopeless cause to try to maintain an
up-to-date database of which features each variant of each operating
system has.  It's easier and more reliable to check for most features on
the fly--especially on hybrid systems that people have hacked on
locally or that have patches from vendors installed.

   I considered using an architecture similar to that of Cygnus
`configure', where there is a single `configure' script that reads
pieces of `configure.in' when run.  But I didn't want to have to
distribute all of the feature tests with every package, so I settled on
having a different `configure' made from each `configure.in' by a
preprocessor.  That approach also offered more control and flexibility.

   I looked briefly into using the Metaconfig package, by Larry Wall,
Harlan Stenn, and Raphael Manfredi, but I decided not to for several
reasons.  The `Configure' scripts it produces are interactive, which I
find quite inconvenient; I didn't like the ways it checked for some
features (such as library functions); I didn't know that it was still
being maintained, and the `Configure' scripts I had seen didn't work on
many modern systems (such as System V R4 and NeXT); it wasn't very
flexible in what it could do in response to a feature's presence or
absence; I found it confusing to learn; and it was too big and complex
for my needs (I didn't realize then how much Autoconf would eventually
have to grow).

   I considered using Perl to generate my style of `configure' scripts,
but decided that `m4' was better suited to the job of simple textual
substitutions: it gets in the way less, because output is implicit.
Plus, everyone already has it.  (Initially I didn't rely on the GNU
extensions to `m4'.)  Also, some of my friends at the University of
Maryland had recently been putting `m4' front ends on several programs,
including `tvtwm', and I was interested in trying out a new language.


File: autoconf.info,  Node: Leviticus,  Next: Numbers,  Prev: Exodus,  Up: History

Leviticus
=========

   Since my `configure' scripts determine the system's capabilities
automatically, with no interactive user intervention, I decided to call
the program that generates them Autoconfig.  But with a version number
tacked on, that name would be too long for old UNIX file systems, so I
shortened it to Autoconf.

   In the fall of 1991 I called together a group of fellow questers
after the Holy Grail of portability (er, that is, alpha testers) to
give me feedback as I encapsulated pieces of my handwritten scripts in
`m4' macros and continued to add features and improve the techniques
used in the checks.  Prominent among the testers were Franc,ois Pinard,
who came up with the idea of making an `autoconf' shell script to run
`m4' and check for unresolved macro calls; Richard Pixley, who
suggested running the compiler instead of searching the file system to
find include files and symbols, for more accurate results; Karl Berry,
who got Autoconf to configure TeX and added the macro index to the
documentation; and Ian Taylor, who added support for creating a C
header file as an alternative to putting `-D' options in a `Makefile',
so he could use Autoconf for his UUCP package.  The alpha testers
cheerfully adjusted their files again and again as the names and
calling conventions of the Autoconf macros changed from release to
release.  They all contributed many specific checks, great ideas, and
bug fixes.


File: autoconf.info,  Node: Numbers,  Next: Deuteronomy,  Prev: Leviticus,  Up: History

Numbers
=======

   In July 1992, after months of alpha testing, I released Autoconf 1.0,
and converted many GNU packages to use it.  I was surprised by how
positive the reaction to it was.  More people started using it than I
could keep track of, including people working on software that wasn't
part of the GNU Project (such as TCL, FSP, and Kerberos V5).  Autoconf
continued to improve rapidly, as many people using the `configure'
scripts reported problems they encountered.

   Autoconf turned out to be a good torture test for `m4'
implementations.  UNIX `m4' started to dump core because of the length
of the macros that Autoconf defined, and several bugs showed up in GNU
`m4' as well.  Eventually, we realized that we needed to use some
features that only GNU `m4' has.  4.3BSD `m4', in particular, has an
impoverished set of builtin macros; the System V version is better, but
still doesn't provide everything we need.

   More development occurred as people put Autoconf under more stresses
(and to uses I hadn't anticipated).  Karl Berry added checks for X11.
david zuhn contributed C++ support.  Franc,ois Pinard made it diagnose
invalid arguments.  Jim Blandy bravely coerced it into configuring GNU
Emacs, laying the groundwork for several later improvements.  Roland
McGrath got it to configure the GNU C Library, wrote the `autoheader'
script to automate the creation of C header file templates, and added a
`--verbose' option to `configure'.  Noah Friedman added the
`--macrodir' option and `AC_MACRODIR' environment variable.  (He also
coined the term "autoconfiscate" to mean "adapt a software package to
use Autoconf".)  Roland and Noah improved the quoting protection in
`AC_DEFINE' and fixed many bugs, especially when I got sick of dealing
with portability problems from February through June, 1993.


File: autoconf.info,  Node: Deuteronomy,  Prev: Numbers,  Up: History

Deuteronomy
===========

   A long wish list for major features had accumulated, and the effect
of several years of patching by various people had left some residual
cruft.  In April 1994, while working for Cygnus Support, I began a major
revision of Autoconf.  I added most of the features of the Cygnus
`configure' that Autoconf had lacked, largely by adapting the relevant
parts of Cygnus `configure' with the help of david zuhn and Ken
Raeburn.  These features include support for using `config.sub',
`config.guess', `--host', and `--target'; making links to files; and
running `configure' scripts in subdirectories.  Adding these features
enabled Ken to convert GNU `as', and Rob Savoye to convert DejaGNU, to
using Autoconf.

   I added more features in response to other peoples' requests.  Many
people had asked for `configure' scripts to share the results of the
checks between runs, because (particularly when configuring a large
source tree, like Cygnus does) they were frustratingly slow.  Mike
Haertel suggested adding site-specific initialization scripts.  People
distributing software that had to unpack on MS-DOS asked for a way to
override the `.in' extension on the file names, which produced file
names like `config.h.in' containing two dots.  Jim Avera did an
extensive examination of the problems with quoting in `AC_DEFINE' and
`AC_SUBST'; his insights led to significant improvements.  Richard
Stallman asked that compiler output be sent to `config.log' instead of
`/dev/null', to help people debug the Emacs `configure' script.

   I made some other changes because of my dissatisfaction with the
quality of the program.  I made the messages showing results of the
checks less ambiguous, always printing a result.  I regularized the
names of the macros and cleaned up coding style inconsistencies.  I
added some auxiliary utilities that I had developed to help convert
source code packages to use Autoconf.  With the help of Franc,ois
Pinard, I made the macros not interrupt each others' messages.  (That
feature revealed some performance bottlenecks in GNU `m4', which he
hastily corrected!) I reorganized the documentation around problems
people want to solve.  And I began a testsuite, because experience had
shown that Autoconf has a pronounced tendency to regress when we change
it.

   Again, several alpha testers gave invaluable feedback, especially
Franc,ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
and Mark Eichin.

   Finally, version 2.0 was ready.  And there was much rejoicing.  (And
I have free time again.  I think.  Yeah, right.)