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.
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, 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.
configure does write the `Makefile', then `Makefile'
should have a target named `Makefile' which causes
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
configure. This is so that users won't think
of trying to edit them by hand.
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.
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
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
VPATH into the Makefile. Some rules may need to
refer explicitly to the specified source directory. To make this
configure can add to the Makefile a variable named
srcdir whose value is precisely the specified directory.
configure script should also take an argument which specifies the
type of system to build the program for. This argument should look like
For example, a Sun 3 might be `m68k-sun-sunos4.1'.
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. So would `sun3-bsd4.2', since SunOS is
basically BSD and no other BSD system is used on a Sun. 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
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 are present on the machine:
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-'. This is so users will be able to configure
an entire GNU source tree at once with a single set of options.
Packages that perform part of compilation may support cross-compilation.
In such a case, the host and target machines for the program may be
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.
The way to build a cross-compiler, cross-assembler, or what have you, is
to specify the option `--host=hosttype' when running
configure. This specifies the host system without changing the
type of target system. The syntax for hosttype is the same as
Programs for which cross-operation is not meaningful need not accept the `--host' option, because configuring an entire operating system for cross-operation is not a meaningful thing.
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.