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

15.1 Controlling Help Output

Users consult `configure --help' to learn of configuration decisions specific to your package. By default, configure breaks this output into sections for each type of option; within each section, help strings appear in the order `configure.ac' defines them:

Optional Features:
  …
  --enable-bar            include bar

Optional Packages:
  …
  --with-foo              use foo

Macro: AC_PRESERVE_HELP_ORDER

Request an alternate `--help' format, in which options of all types appear together, in the order defined. Call this macro before any AC_ARG_ENABLE or AC_ARG_WITH.

Optional Features and Packages: … --enable-bar include bar --with-foo use foo

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

Normally configure scripts complain about `--with-package' options that they do not support. See section Controlling Checking of configure Options, for details, and for how to override the defaults.

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]@c, [action-if-not-given]@c)

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, dashes, and dots.

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 named with_package, with any non-alphanumeric characters in package 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. The easiest way to provide the proper leading whitespace is to format your help-string with the macro AS_HELP_STRING (see section Making Your Help Strings Look Pretty).

The following example shows how to use the AC_ARG_WITH macro in a common situation. You want to let the user decide whether to enable support for an external library (e.g., the readline library); if the user specified neither `--with-readline' nor `--without-readline', you want to enable support for readline only if the library is available on the system.

AC_ARG_WITH([readline], [AS_HELP_STRING([--with-readline], [support fancy command line editing @<:@default=check@:>@])], [], [with_readline=check]) LIBREADLINE= AS_IF([test "x$with_readline" != xno], [AC_CHECK_LIB([readline], [main], [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) AC_DEFINE([HAVE_LIBREADLINE], [1], [Define if you have libreadline]) ], [if test "x$with_readline" != xcheck; then AC_MSG_FAILURE( [--with-readline was given, but test for readline failed]) fi ], -lncurses)])

The next example shows how to use AC_ARG_WITH to give the user the possibility to enable support for the readline library, in case it is still experimental and not well tested, and is therefore disabled by default.

AC_ARG_WITH([readline], [AS_HELP_STRING([--with-readline], [enable experimental support for readline])], [], [with_readline=no]) LIBREADLINE= AS_IF([test "x$with_readline" != xno], [AC_CHECK_LIB([readline], [main], [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) AC_DEFINE([HAVE_LIBREADLINE], [1], [Define if you have libreadline]) ], [AC_MSG_FAILURE( [--with-readline was given, but test for readline failed])], [-lncurses])])

The last example shows how to use AC_ARG_WITH to give the user the possibility to disable support for the readline library, given that it is an important feature and that it should be enabled by default.

AC_ARG_WITH([readline], [AS_HELP_STRING([--without-readline], [disable support for readline])], [], [with_readline=yes]) LIBREADLINE= AS_IF([test "x$with_readline" != xno], [AC_CHECK_LIB([readline], [main], [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) AC_DEFINE([HAVE_LIBREADLINE], [1], [Define if you have libreadline]) ], [AC_MSG_FAILURE( [readline test failed (--without-readline to disable)])], [-lncurses])])

These three examples can be easily adapted to the case where AC_ARG_ENABLE should be preferred to AC_ARG_WITH (see Choosing Package Options).

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

Normally configure scripts complain about `--enable-package' options that they do not support. See section Controlling Checking of configure Options, for details, and for how to override the defaults.

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]@c, [action-if-not-given]@c)

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, dashes, and dots.

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 named enable_feature, with any non-alphanumeric characters in feature 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 AS_HELP_STRING (see section Making Your Help Strings Look Pretty).

See the examples suggested with the definition of AC_ARG_WITH (see section Working With External Software) to get an idea of possible applications of AC_ARG_ENABLE.

15.4 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 AS_HELP_STRING macro.

Macro: AS_HELP_STRING (left-hand-side, right-hand-side   [indent-column = `26']@c, [wrap-column = `79']@c)

Expands into a 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 makes this clearer.

AC_ARG_WITH([foo], [AS_HELP_STRING([--with-foo], [use foo (default is no)])], [use_foo=$withval], [use_foo=no])

Then the last few lines of `configure --help' appear like this:

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

Macro expansion is performed on the first argument. However, the second argument of AS_HELP_STRING is treated as a whitespace separated list of text to be reformatted, and is not subject to macro expansion. Since it is not expanded, it should not be double quoted. See section The Autoconf Language, for a more detailed explanation.

The AS_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. Be aware that left-hand-side may not expand to unbalanced quotes, although quadrigraphs can be used.

AC_DEFUN([MY_ARG_WITH], [AC_ARG_WITH(m4_translit([[$1]], [_], [-]), [AS_HELP_STRING([--with-m4_translit([$1], [_], [-])], [use $1 (default is $2)])], [use_[]$1=$withval], [use_[]$1=$2])]) MY_ARG_WITH([a_b], [no])

Here, the last few lines of `configure --help' will include:

--enable and --with options recognized: --with-a-b use a_b (default is no)

The parameters indent-column and wrap-column were introduced in Autoconf 2.62. Generally, they should not be specified; they exist for fine-tuning of the wrapping.

AS_HELP_STRING([--option], [description of option]) ⇒ --option description of option AS_HELP_STRING([--option], [description of option], [15], [30]) ⇒ --option description of ⇒ option

15.5 Controlling Checking of configure Options

The configure script checks its command-line options against a list of known options, like `--help' or `--config-cache'. An unknown option ordinarily indicates a mistake by the user and configure halts with an error. However, by default unknown `--with-package' and `--enable-feature' options elicit only a warning, to support configuring entire source trees.

Source trees often contain multiple packages with a top-level configure script that uses the AC_CONFIG_SUBDIRS macro (see section Configuring Other Packages in Subdirectories). Because the packages generally support different `--with-package' and `--enable-feature' options, the GNU Coding Standards say they must accept unrecognized options without halting. Even a warning message is undesirable here, so AC_CONFIG_SUBDIRS automatically disables the warnings.

This default behavior may be modified in two ways. First, the installer can invoke configure --disable-option-checking to disable these warnings, or invoke configure --enable-option-checking=fatal options to turn them into fatal errors, respectively. Second, the maintainer can use AC_DISABLE_OPTION_CHECKING.

Macro: AC_DISABLE_OPTION_CHECKING

By default, disable warnings related to any unrecognized `--with-package' or `--enable-feature' options. This is implied by AC_CONFIG_SUBDIRS.

The installer can override this behavior by passing `--enable-option-checking' (enable warnings) or `--enable-option-checking=fatal' (enable errors) to configure.

15.6 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 runtime, rather than at compile time. Runtime 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.

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

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

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

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

15.8 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, see the documentation of the respective Autoconf macro. If the variables or their semantics are undocumented, you may need to look for shell variables with `_cv_' in their names in the affected configure scripts, or in the Autoconf M4 source code for those macros; but in that case, their name or semantics may change in a future Autoconf version.

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

# /usr/share/local/gnu/share/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

Another use of `config.site' is for priming the directory variables in a manner consistent with the Filesystem Hierarchy Standard (FHS). Once the following file is installed at `/usr/share/config.site', a user can execute simply ./configure --prefix=/usr to get all the directories chosen in the locations recommended by FHS.

# /usr/share/config.site for FHS defaults when installing below /usr,
# and the respective settings were not changed on the command line.
if test "$prefix" = /usr; then
  test "$sysconfdir" = '${prefix}/etc' && sysconfdir=/etc
  test "$sharedstatedir" = '${prefix}/com' && sharedstatedir=/var
  test "$localstatedir" = '${prefix}/var' && localstatedir=/var
fi

Likewise, on platforms where 64-bit libraries are built by default, then installed in `/usr/local/lib64' instead of `/usr/local/lib', it is appropriate to install `/usr/local/share/config.site':

# /usr/local/share/config.site for platforms that prefer
# the directory /usr/local/lib64 over /usr/local/lib.
test "$libdir" = '${exec_prefix}/lib' && libdir='${exec_prefix}/lib64'

This document was generated on January, 20 2010 using texi2html 1.76.