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