standards: Configuration
1
1 7.1 How Configuration Should Work
1 =================================
1
1 Each GNU distribution should come with a shell script named 'configure'.
1 This script is given arguments which describe the kind of machine and
1 system you want to compile the program for. The 'configure' script must
1 record the configuration options so that they affect compilation.
1
1 The description here is the specification of the interface for the
1 'configure' script in GNU packages. Many packages implement it using
1 GNU Autoconf (⇒Introduction (autoconf)Top.) and/or GNU Automake
1 (⇒Introduction (automake)Top.), but you do not have to use these
1 tools. You can implement it any way you like; for instance, by making
1 'configure' be a wrapper around a completely different configuration
1 system.
1
1 Another way for the 'configure' script to operate is to make a link
1 from a standard name such as 'config.h' to the proper configuration file
1 for the chosen system. If you use this technique, the distribution
1 should _not_ contain a file named 'config.h'. This is so that people
1 won't be able to build the program without configuring it first.
1
1 Another thing that 'configure' can do is to edit the Makefile. If
1 you do this, the distribution should _not_ contain a file named
1 'Makefile'. Instead, it should include a file 'Makefile.in' which
1 contains the input used for editing. Once again, this is so that people
1 won't be able to build the program without configuring it first.
1
1 If 'configure' does write the 'Makefile', then 'Makefile' should have
1 a target named 'Makefile' which causes 'configure' to be rerun, setting
1 up the same configuration that was set up last time. The files that
1 'configure' reads should be listed as dependencies of 'Makefile'.
1
1 All the files which are output from the 'configure' script should
1 have comments at the beginning explaining that they were generated
1 automatically using 'configure'. This is so that users won't think of
1 trying to edit them by hand.
1
1 The 'configure' script should write a file named 'config.status'
1 which describes which configuration options were specified when the
1 program was last configured. This file should be a shell script which,
1 if run, will recreate the same configuration.
1
1 The 'configure' script should accept an option of the form
1 '--srcdir=DIRNAME' to specify the directory where sources are found (if
1 it is not the current directory). This makes it possible to build the
1 program in a separate directory, so that the actual source directory is
1 not modified.
1
1 If the user does not specify '--srcdir', then 'configure' should
1 check both '.' and '..' to see if it can find the sources. If it finds
1 the sources in one of these places, it should use them from there.
1 Otherwise, it should report that it cannot find the sources, and should
1 exit with nonzero status.
1
1 Usually the easy way to support '--srcdir' is by editing a definition
1 of 'VPATH' into the Makefile. Some rules may need to refer explicitly
1 to the specified source directory. To make this possible, 'configure'
1 can add to the Makefile a variable named 'srcdir' whose value is
1 precisely the specified directory.
1
1 In addition, the 'configure' script should take options corresponding
11 to most of the standard directory variables (⇒Directory
Variables). Here is the list:
1
1 --prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir
1 --sharedstatedir --localstatedir --runstatedir
1 --libdir --includedir --oldincludedir
1 --datarootdir --datadir --infodir --localedir --mandir --docdir
1 --htmldir --dvidir --pdfdir --psdir
1
1 The 'configure' script should also take an argument which specifies
1 the type of system to build the program for. This argument should look
1 like this:
1
1 CPU-COMPANY-SYSTEM
1
1 For example, an Athlon-based GNU/Linux system might be
1 'i686-pc-linux-gnu'.
1
1 The 'configure' script needs to be able to decode all plausible
1 alternatives for how to describe a machine. Thus, 'athlon-pc-gnu/linux'
1 would be a valid alias. There is a shell script called 'config.sub'
1 (http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD)
1 that you can use as a subroutine to validate system types and
1 canonicalize aliases.
1
1 The 'configure' script should also take the option
1 '--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
1 argument. For example, 'configure --build=i686-pc-linux-gnu' is
1 equivalent to 'configure i686-pc-linux-gnu'. When the build type is not
1 specified by an option or argument, the 'configure' script should
1 normally guess it using the shell script 'config.guess'
1 (http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD).
1
1 Other options are permitted to specify in more detail the software or
1 hardware present on the machine, to include or exclude optional parts of
1 the package, or to adjust the name of some tools or arguments to them:
1
1 '--enable-FEATURE[=PARAMETER]'
1 Configure the package to build and install an optional user-level
1 facility called FEATURE. This allows users to choose which
1 optional features to include. Giving an optional PARAMETER of 'no'
1 should omit FEATURE, if it is built by default.
1
1 No '--enable' option should *ever* cause one feature to replace
1 another. No '--enable' option should ever substitute one useful
1 behavior for another useful behavior. The only proper use for
1 '--enable' is for questions of whether to build part of the program
1 or exclude it.
1
1 '--with-PACKAGE'
1 The package PACKAGE will be installed, so configure this package to
1 work with PACKAGE.
1
1 Possible values of PACKAGE include 'gnu-as' (or 'gas'), 'gnu-ld',
1 'gnu-libc', 'gdb', 'x', and 'x-toolkit'.
1
1 Do not use a '--with' option to specify the file name to use to
1 find certain files. That is outside the scope of what '--with'
1 options are for.
1
1 'VARIABLE=VALUE'
1 Set the value of the variable VARIABLE to VALUE. This is used to
1 override the default values of commands or arguments in the build
1 process. For example, the user could issue 'configure CFLAGS=-g
1 CXXFLAGS=-g' to build with debugging information and without the
1 default optimization.
1
1 Specifying variables as arguments to 'configure', like this:
1 ./configure CC=gcc
1 is preferable to setting them in environment variables:
1 CC=gcc ./configure
1 as it helps to recreate the same configuration later with
1 'config.status'. However, both methods should be supported.
1
1 All 'configure' scripts should accept all of the "detail" options and
1 the variable settings, whether or not they make any difference to the
1 particular package at hand. In particular, they should accept any
1 option that starts with '--with-' or '--enable-'. This is so users will
1 be able to configure an entire GNU source tree at once with a single set
1 of options.
1
1 You will note that the categories '--with-' and '--enable-' are
1 narrow: they *do not* provide a place for any sort of option you might
1 think of. That is deliberate. We want to limit the possible
1 configuration options in GNU software. We do not want GNU programs to
1 have idiosyncratic configuration options.
1
1 Packages that perform part of the compilation process may support
1 cross-compilation. In such a case, the host and target machines for the
1 program may be different.
1
1 The 'configure' script should normally treat the specified type of
1 system as both the host and the target, thus producing a program which
1 works for the same type of machine that it runs on.
1
1 To compile a program to run on a host type that differs from the
1 build type, use the configure option '--host=HOSTTYPE', where HOSTTYPE
1 uses the same syntax as BUILDTYPE. The host type normally defaults to
1 the build type.
1
1 To configure a cross-compiler, cross-assembler, or what have you, you
1 should specify a target different from the host, using the configure
1 option '--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
1 for the host type. So the command would look like this:
1
1 ./configure --host=HOSTTYPE --target=TARGETTYPE
1
1 The target type normally defaults to the host type. Programs for
1 which cross-operation is not meaningful need not accept the '--target'
1 option, because configuring an entire operating system for
1 cross-operation is not a meaningful operation.
1
1 Some programs have ways of configuring themselves automatically. If
1 your program is set up to do this, your 'configure' script can simply
1 ignore most of its arguments.
1