Go to the first, previous, next, last section, table of contents.
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
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=@ovar{arg}
--without-package
For example, @option{--with-gnu-ld} means work with the GNU linker instead of some other linker. @option{--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'. @option{--without-package} is equivalent to @option{--with-package=no}.
configure scripts do not complain about
@option{--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.
configure the option @option{--with-package}
or @option{--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 @option{-} 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 it 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).
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=@ovar{arg}
--disable-feature
These options allow users to choose which optional features to build and install. @option{--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 @option{--enable-debug=stabs}. If no argument is given, it defaults to `yes'. @option{--disable-feature} is equivalent to @option{--enable-feature=no}.
configure scripts do not complain about
@option{--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.
configure the option
@option{--enable-feature} or @option{--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 @option{-} 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).
AC_ARG_ENABLE that does not
support providing a help string.
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.
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)])
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.ac' 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_TARGET has been called and a @option{--target} value
is given that differs from the host type (specified with @option{--host}),
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:
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 @option{--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
@option{--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 @option{--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.
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
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.
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 @option{--without-} and @option{--disable-} options
are like giving the corresponding @option{--with-} or @option{--enable-}
option and the value `no'. Thus, @option{--cache-file=localcache}
sets the variable cache_file to the value `localcache';
@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
enable_warnings to the value `no'; @option{--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" = /dev/null; 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.