configure scripts support several kinds of local configuration
decisions. There are ways for users to specify where external software
packages are, include or exclude optional features, install programs
under modified names, and set default values for configure
options.
Some packages require, or can optionally use, other software packages
which are already installed. The user can give configure
command line options to specify which such external software to use.
The options have one of these forms:
--with-package[=arg] --without-package
For example, `--with-gnu-ld' means work with the GNU linker instead of some other linker. `--with-x' means work with The X Window System.
The user can give an argument by following the package name with `=' and the argument. Giving an argument of `no' is for packages that are used by default; it says to not use the package. An argument that is neither `yes' nor `no' could include a name or number of a version of the other package, to specify more precisely which other package this program is supposed to work with. If no argument is given, it defaults to `yes'. `--without-package' is equivalent to `--with-package=no'.
configure scripts do not complain about
`--with-package' options that they do not support.
This behavior permits configuring a source tree containing multiple
packages with a top-level configure script when the packages
support different options, without spurious error messages about options
that some of the packages support.
An unfortunate side effect is that option spelling errors are not diagnosed.
No better approach to this problem has been suggested so far.
For each external software package that may be used, `configure.in'
should call AC_ARG_WITH to detect whether the configure
user asked to use it. Whether each package is used or not by
default, and which arguments are valid, is up to you.
configure the option `--with-package'
or `--without-package', run shell commands
action-if-given. If neither option was given, run shell commands
action-if-not-given. The name package indicates another
software package that this program should work with. It should consist
only of alphanumeric characters and dashes.
The option's argument is available to the shell commands
action-if-given in the shell variable withval, which is
actually just the value of the shell variable with_package,
with any `-' characters changed into `_'.
You may use that variable instead, if you wish.
The argument help-string is a description of the option which looks like this:
--with-readline support fancy command line editing
help-string may be more than one line long, if more detail is needed. Just make sure the columns line up in `configure --help'. Avoid tabs in the help string. You'll need to enclose it in `[' and `]' in order to produce the leading spaces.
AC_ARG_WITH that does not
support providing a help string.
If a software package has optional compile-time features, the user can
give configure command line options to specify whether to
compile them. The options have one of these forms:
--enable-feature[=arg] --disable-feature
These options allow users to choose which optional features to build and install. `--enable-feature' options should never make a feature behave differently or cause one feature to replace another. They should only cause parts of the program to be built rather than left out.
The user can give an argument by following the feature name with `=' and the argument. Giving an argument of `no' requests that the feature not be made available. A feature with an argument looks like `--enable-debug=stabs'. If no argument is given, it defaults to `yes'. `--disable-feature' is equivalent to `--enable-feature=no'.
configure scripts do not complain about
`--enable-feature' options that they do not support.
This behavior permits configuring a source tree containing multiple
packages with a top-level configure script when the packages
support different options, without spurious error messages about options
that some of the packages support.
An unfortunate side effect is that option spelling errors are not diagnosed.
No better approach to this problem has been suggested so far.
For each optional feature, `configure.in' should call
AC_ARG_ENABLE to detect whether the configure user asked
to include it. Whether each feature is included or not by default, and
which arguments are valid, is up to you.
configure the option
`--enable-feature' or `--disable-feature', run
shell commands action-if-given. If neither option was given, run
shell commands action-if-not-given. The name feature
indicates an optional user-level facility. It should consist only of
alphanumeric characters and dashes.
The option's argument is available to the shell commands
action-if-given in the shell variable enableval, which is
actually just the value of the shell variable
enable_feature, with any `-' characters changed into
`_'. You may use that variable instead, if you wish. The
help-string argument is like that of AC_ARG_WITH
(see section Working With External Software).
AC_ARG_ENABLE that does not
support providing a help string.
Some software packages require complex site-specific information. Some examples are host names to use for certain services, company names, and email addresses to contact. Since some configuration scripts generated by Metaconfig ask for such information interactively, people sometimes wonder how to get that information in Autoconf-generated configuration scripts, which aren't interactive.
Such site configuration information should be put in a file that is
edited only by users, not by programs. The location of the file
can either be based on the prefix variable, or be a standard
location such as the user's home directory. It could even be specified
by an environment variable. The programs should examine that file at
run time, rather than at compile time. Run time configuration is more
convenient for users and makes the configuration process simpler than
getting the information while configuring. See section `Variables for Installation Directories' in GNU Coding Standards, for more information on where to put data files.
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.
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.
You can specify name transformations by giving configure these
command line options:
--program-prefix=prefix
--program-suffix=suffix
--program-transform-name=expression
sed substitution expression on the names.
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 sophisticated 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.
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.
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.
You can examine or override the value set by a command line option to
configure in a site file; options set shell variables that have
the same names as the options, with any dashes turned into underscores.
The exceptions are that `--without-' and `--disable-' options
are like giving the corresponding `--with-' or `--enable-'
option and the value `no'. Thus, `--cache-file=localcache'
sets the variable cache_file to the value `localcache';
`--enable-warnings=no' or `--disable-warnings' sets the variable
enable_warnings to the value `no'; `--prefix=/usr' sets the
variable prefix to the value `/usr'; etc.
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
#
# Change some defaults.
test "$prefix" = NONE && prefix=/usr/share/local/gnu
test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
test "$sharedstatedir" = '${prefix}/com' && sharedstatedir=/var
test "$localstatedir" = '${prefix}/var' && localstatedir=/var
#
# 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
Go to the first, previous, next, last section, table of contents.