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

12.1 Working With External Software

Some packages require, or can optionally use, other software packages that 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.ac' 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-given], [action-if-not-given])

If the user gave 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 that 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 the help string in `[' and `]' in order to produce the leading spaces.

You should format your help-string with the macro AC_HELP_STRING (see section Making Your Help Strings Look Pretty).

Macro: AC_WITH (package, action-if-given, [action-if-not-given])

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

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

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.ac' 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-given], [action-if-not-given])

If the user gave 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).

You should format your help-string with the macro AC_HELP_STRING (see section Making Your Help Strings Look Pretty).

Macro: AC_ENABLE (feature, action-if-given, [action-if-not-given])

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

12.3 Making Your Help Strings Look Pretty

Properly formatting the `help strings' which are used in AC_ARG_WITH (see section Working With External Software) and AC_ARG_ENABLE (see section Choosing Package Options) can be challenging. Specifically, you want your own `help strings' to line up in the appropriate columns of `configure --help' just like the standard Autoconf `help strings' do. This is the purpose of the AC_HELP_STRING macro.

Macro: AC_HELP_STRING (left-hand-side, right-hand-side)

Expands into an help string that looks pretty when the user executes `configure --help'. It is typically used in AC_ARG_WITH (see section Working With External Software) or AC_ARG_ENABLE (see section Choosing Package Options). The following example will make this clearer.

AC_DEFUN([TEST_MACRO], [AC_ARG_WITH([foo], AC_HELP_STRING([--with-foo], [use foo (default is NO)]), [ac_cv_use_foo=$withval], [ac_cv_use_foo=no]) AC_CACHE_CHECK([whether to use foo], [ac_cv_use_foo], [ac_cv_use_foo=no])])

Please note that the call to AC_HELP_STRING is unquoted. Then the last few lines of `configure --help' will appear like this:

--enable and --with options recognized: --with-foo use foo (default is NO)

The AC_HELP_STRING macro is particularly helpful when the left-hand-side and/or right-hand-side are composed of macro arguments, as shown in the following example.

AC_DEFUN(MY_ARG_WITH, [AC_ARG_WITH([$1], AC_HELP_STRING([--with-$1], [use $1 (default is $2)]), ac_cv_use_$1=$withval, ac_cv_use_$1=no), AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])

12.4 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. Run-time configuration is more convenient for users and makes the configuration process simpler than getting the information while configuring. See (standards)Directory Variables section `Variables for Installation Directories' in GNU Coding Standards, for more information on where to put data files.

12.5 Transforming Program Names When Installing

Autoconf supports changing the names of programs when installing them. In order to use these transformations, `configure.ac' 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_TARGET has been called and a `--target' value is given, the target type followed by a dash is used as a prefix. Otherwise, no program name transformation is done.

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

12.5.2 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 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. Nevertheless, pay attention that only the binaries are renamed, therefore you'd have problems with the library files which might overlap.

12.5.3 Transformation Rules

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

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

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

It is guaranteed that program_transform_name is never empty, and that there are no useless separators. Therefore you may safely embed program_transform_name within a sed program using `;':

transform = @program_transform_name@
transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/

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.

12.6 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 (see section Cache Files). 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, where 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" = /dev/null; then
  cache_file="$prefix/var/config.cache"
  # A cache file is only valid for one C compiler.
  CC=gcc
fi

This document was generated by John Paul Wallington on October, 29 2003 using texi2html 1.67.