3.1 Configuring

A `configure' script takes a large number of command line options. The set of options can vary from one package to the next, although a number of basic options are always present. The available options can be discovered by running `configure' with the `--help' option. Although many of these options are esoteric, it's worthwhile knowing of their existence when configuring packages with special installation requirements. Each option will be briefly described below:

`--cache-file=file'

`configure' runs tests on your system to determine the availability of features (or bugs!). The results of these tests can be stored in a cache file to speed up subsequent invocations of configure. The presence of a well primed cache file makes a big improvement when configuring a complex tree which has `configure' scripts in each subtree.

`--help'

Outputs a help message. Even experienced users of `configure' need to use `--help' occasionally, as complex projects will include additional options for per-project configuration. For example, `configure' in the GCC package allows you to control whether the GNU assembler will be built and used by GCC in preference to a vendor's assembler.

`--no-create'

One of the primary functions of `configure' is to generate output files. This option prevents `configure' from generating such output files. You can think of this as a kind of dry run, although the cache will still be modified.

`--quiet'

`--silent'

As `configure' runs its tests, it outputs brief messages telling the user what the script is doing. This was done because `configure' can be slow. If there was no such output, the user would be left wondering what is happening. By using this option, you too can be left wondering!

`--version'

Prints the version of Autoconf that was used to generate the `configure' script.

`--prefix=prefix'

The --prefix option is one of the most frequently used. If generated `Makefile's choose to observe the argument you pass with this option, it is possible to entirely relocate the architecture-independent portion of a package when it is installed. For example, when installing a package like Emacs, the following command line will cause the Emacs Lisp files to be installed in `/opt/gnu/share':

$ ./configure --prefix=/opt/gnu

It is important to stress that this behavior is dependent on the generated files making use of this information. For developers writing these files, Automake simplifies this process a great deal. Automake is introduced in 7. Introducing GNU Automake.

`--exec-prefix=eprefix'

Similar to `--prefix', except that it sets the location of installed files which are architecture-dependent. The compiled `emacs' binary is such a file. If this option is not given, the default `exec-prefix' value inserted into generated files is set to the same values at the `prefix'.

`--bindir=dir'

Specifies the location of installed binary files. While there may be other generated files which are binary in nature, binary files here are defined to be programs that are run directly by users.

`--sbindir=dir'

Specifies the location of installed superuser binary files. These are programs which are usually only run by the superuser.

`--libexecdir=dir'

Specifies the location of installed executable support files. Contrasted with `binary files', these files are never run directly by users, but may be executed by the binary files mentioned above.

`--datadir=dir'

Specifies the location of generic data files.

`--sysconfdir=dir'

Specifies the location of read-only data used on a single machine.

`--sharedstatedir=dir'

Specifies the location of data which may be modified, and which may be shared across several machines.

`--localstatedir=dir'

Specifies the location of data which may be modified, but which is specific to a single machine.

`--libdir=dir'

Specifies where object code library should be installed.

`--includedir=dir'

Specifies where C header files should be installed. Header files for other languages such as C++ may be installed here also.

`--oldincludedir=dir'

Specifies where C header files should be installed for compilers other than GCC.

`--infodir=dir'

Specifies where Info format documentation files should be installed. Info is the documentation format used by the GNU project.

`--mandir=dir'

Specifies where manual pages should be installed.

`--srcdir=dir'

This option does not affect installation. Instead, it tells `configure' where the source files may be found. It is normally not necessary to specify this, since the configure script is normally in the same directory as the source files.

`--program-prefix=prefix'

Specifies a prefix which should be added to the name of a program when installing it. For example, using `--program-prefix=g' when configuring a program normally named `tar' will cause the installed program to be named `gtar' instead. As with the other installation options, this `configure' option only works if it is utilized by the `Makefile.in' file.

`--program-suffix=suffix'

Specifies a suffix which should be appended to the name of a program when installing it.

`--program-transform-name=program'

Here, program is a sed script. When a program is installed, its name will be run through `sed -e script' to produce the installed name.

`--build=build'

Specifies the type of system on which the package will be built. If not specified, the default will be the same configuration name as the host.

`--host=host'

Specifies the type of system on which the package will run--or be hosted. If not specified, the host triplet is determined by executing `config.guess'.

`--target=target'

Specifies the type of system which the package is to be targeted to. This makes the most sense in the context of programming language tools like compilers and assemblers. If not specified, the default will be the same configuration name as the host.

`--disable-feature'

Some packages may choose to provide compile-time configurability for large-scale options such as using the Kerberos authentication system or an experimental compiler optimization pass. If the default is to provide such features, they may be disabled with `--disable-feature', where feature is the feature's designated name. For example:

$ ./configure --disable-gui

`--enable-feature[=arg]'

Conversely, some packages may provide features which are disabled by default. To enable them, use `--enable-feature', where feature is the feature's designated name. A feature may accept an optional argument. For example:

$ ./configure --enable-buffers=128

Using `--enable-feature=no' is synonymous with `--disable-feature', described above.

`--with-package[=arg]'

In the free software community, there is a healthy tendency to reuse existing packages and libraries where possible. At the time when a source tree is configured by `configure', it is possible to provide hints about other installed packages. For example, the BLT widget toolkit relies on Tcl and Tk. To configure BLT, it may be necessary to give `configure' some hints about where you have installed Tcl and Tk:

$ ./configure --with-tcl=/usr/local --with-tk=/usr/local

Using `--with-package=no' is synonymous with `--without-package' which is described below.

`--without-package'

Sometimes you may not want your package to inter-operate with some pre-existing package installed on your system. For example, you might not want your new compiler to use GNU ld. You can prevent this by using an option such as:

$ ./configure --without-gnu-ld

`--x-includes=dir'

This option is really a specific instance of a `--with-package' option. At the time when Autoconf was initially being developed, it was common to use `configure' to build programs to run on the X Window System as an alternative to Imake. The `--x-includes' option provides a way to guide the configure script to the directory containing the X11 header files.

`--x-libraries=dir'

Similarly, the --x-libraries option provides a way to guide `configure' to the directory containing the X11 libraries.

It is unnecessary, and often undesirable, to run `configure' from within the source tree. Instead, a well-written `Makefile' generated by `configure' will be able to build packages whose source files reside in another tree. The advantages of building derived files in a separate tree to the source code are fairly obvious: the derived files, such as object files, would clutter the source tree. This would also make it impossible to build those same object files on a different system or with a different configuration. Instead, it is recommended to use three trees: a source tree, a build tree and an install tree. Here is a closing example of how to build the GNU malloc package in this way:

$ gtar zxf mmalloc-1.0.tar.gz $ mkdir build && cd build $ ../mmalloc-1.0/configure creating cache ./config.cache checking for gcc... gcc checking whether the C compiler (gcc ) works... yes checking whether the C compiler (gcc ) is a cross-compiler... no checking whether we are using GNU C... yes checking whether gcc accepts -g... yes checking for a BSD compatible install... /usr/bin/install -c checking host system type... i586-pc-linux-gnu checking build system type... i586-pc-linux-gnu checking for ar... ar checking for ranlib... ranlib checking how to run the C preprocessor... gcc -E checking for unistd.h... yes checking for getpagesize... yes checking for working mmap... yes checking for limits.h... yes checking for stddef.h... yes updating cache ../config.cache creating ./config.status

Now that this build tree is configured, it is possible to go on and build the package and install it into the default location of `/usr/local':

$ make all && make install