Go to the previous, next section.

Site Configuration

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.

Working With External Software

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-x11' means work with X11.

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

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.

Macro: AC_ARG_WITH (package, help-string, action-if-true [, action-if-false])

@maindex ARG_WITH If the user gave configure the option `--with-package' or `--without-package', run shell commands action-if-true. Otherwise run shell commands action-if-false. 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-true in the shell variable withval.

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.

Macro: AC_WITH (package, action-if-true [, action-if-false])

@maindex WITH This is an obsolete version of AC_ARG_WITH that does not support providing a help string.

Choosing Package Options

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

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.

Macro: AC_ARG_ENABLE (feature, help-string, action-if-true [, action-if-false])

@maindex ARG_ENABLE If the user gave configure the option `--enable-feature' or `--disable-feature', run shell commands action-if-true. Otherwise run shell commands action-if-false. 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-true in the shell variable enableval. The help-string argument is like that of AC_ARG_WITH (see section Working With External Software).

Macro: AC_ENABLE (feature, action-if-true [, action-if-false])

@maindex ENABLE This is an obsolete version of AC_ARG_ENABLE that does not support providing a help string.

Configuring Site Details

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. That approach 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.

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

@maindex ARG_PROGRAM @ovindex program_transform_name 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.

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.

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.

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.

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.

@evindex CONFIG_SITE 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

Go to the previous, next section.