GNU Info

(standards.info)Configuration

---

Next: Makefile Conventions Up: Managing Releases

---

Enter node , (file) or (file)node

How Configuration Should Work
=============================

   Each GNU distribution should come with a shell script named
`configure'.  This script is given arguments which describe the kind of
machine and system you want to compile the program for.

   The `configure' script must record the configuration options so that
they affect compilation.

   One way to do this is to make a link from a standard name such as
`config.h' to the proper configuration file for the chosen system.  If
you use this technique, the distribution should _not_ contain a file
named `config.h'.  This is so that people won't be able to build the
program without configuring it first.

   Another thing that `configure' can do is to edit the Makefile.  If
you do this, the distribution should _not_ contain a file named
`Makefile'.  Instead, it should include a file `Makefile.in' which
contains the input used for editing.  Once again, this is so that people
won't be able to build the program without configuring it first.

   If `configure' does write the `Makefile', then `Makefile' should
have a target named `Makefile' which causes `configure' to be rerun,
setting up the same configuration that was set up last time.  The files
that `configure' reads should be listed as dependencies of `Makefile'.

   All the files which are output from the `configure' script should
have comments at the beginning explaining that they were generated
automatically using `configure'.  This is so that users won't think of
trying to edit them by hand.

   The `configure' script should write a file named `config.status'
which describes which configuration options were specified when the
program was last configured.  This file should be a shell script which,
if run, will recreate the same configuration.

   The `configure' script should accept an option of the form
`--srcdir=DIRNAME' to specify the directory where sources are found (if
it is not the current directory).  This makes it possible to build the
program in a separate directory, so that the actual source directory is
not modified.

   If the user does not specify `--srcdir', then `configure' should
check both `.' and `..' to see if it can find the sources.  If it finds
the sources in one of these places, it should use them from there.
Otherwise, it should report that it cannot find the sources, and should
exit with nonzero status.

   Usually the easy way to support `--srcdir' is by editing a
definition of `VPATH' into the Makefile.  Some rules may need to refer
explicitly to the specified source directory.  To make this possible,
`configure' can add to the Makefile a variable named `srcdir' whose
value is precisely the specified directory.

   The `configure' script should also take an argument which specifies
the type of system to build the program for.  This argument should look
like this:

     CPU-COMPANY-SYSTEM

   For example, a Sun 3 might be `m68k-sun-sunos4.1'.

   The `configure' script needs to be able to decode all plausible
alternatives for how to describe a machine.  Thus, `sun3-sunos4.1'
would be a valid alias.  For many programs, `vax-dec-ultrix' would be
an alias for `vax-dec-bsd', simply because the differences between
Ultrix and BSD are rarely noticeable, but a few programs might need to
distinguish them.

   There is a shell script called `config.sub' that you can use as a
subroutine to validate system types and canonicalize aliases.

   Other options are permitted to specify in more detail the software
or hardware present on the machine, and include or exclude optional
parts of the package:

`--enable-FEATURE[=PARAMETER]'
     Configure the package to build and install an optional user-level
     facility called FEATURE.  This allows users to choose which
     optional features to include.  Giving an optional PARAMETER of
     `no' should omit FEATURE, if it is built by default.

     No `--enable' option should *ever* cause one feature to replace
     another.  No `--enable' option should ever substitute one useful
     behavior for another useful behavior.  The only proper use for
     `--enable' is for questions of whether to build part of the program
     or exclude it.

`--with-PACKAGE'
     The package PACKAGE will be installed, so configure this package
     to work with PACKAGE.

     Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
     `gnu-libc', `gdb', `x', and `x-toolkit'.

     Do not use a `--with' option to specify the file name to use to
     find certain files.  That is outside the scope of what `--with'
     options are for.

   All `configure' scripts should accept all of these "detail" options,
whether or not they make any difference to the particular package at
hand.  In particular, they should accept any option that starts with
`--with-' or `--enable-'.  This is so users will be able to configure
an entire GNU source tree at once with a single set of options.

   You will note that the categories `--with-' and `--enable-' are
narrow: they *do not* provide a place for any sort of option you might
think of.  That is deliberate.  We want to limit the possible
configuration options in GNU software.  We do not want GNU programs to
have idiosyncratic configuration options.

   Packages that perform part of the compilation process may support
cross-compilation.  In such a case, the host and target machines for the
program may be different.

   The `configure' script should normally treat the specified type of
system as both the host and the target, thus producing a program which
works for the same type of machine that it runs on.

   To configure a cross-compiler, cross-assembler, or what have you, you
should specify a target different from the host, using the configure
option `--target=TARGETTYPE'.  The syntax for TARGETTYPE is the same as
for the host type.  So the command would look like this:

     ./configure HOSTTYPE --target=TARGETTYPE

   Programs for which cross-operation is not meaningful need not accept
the `--target' option, because configuring an entire operating system
for cross-operation is not a meaningful operation.

   Bootstrapping a cross-compiler requires compiling it on a machine
other than the host it will run on.  Compilation packages accept a
configuration option `--build=BUILDTYPE' for specifying the
configuration on which you will compile them, but the configure script
should normally guess the build machine type (using `config.guess'), so
this option is probably not necessary.  The host and target types
normally default from the build type, so in bootstrapping a
cross-compiler you must specify them both explicitly.

   Some programs have ways of configuring themselves automatically.  If
your program is set up to do this, your `configure' script can simply
ignore most of its arguments.