configure
configure
prepares source directories for building programs in
them. "Configuring" is the process of preparing software to compile
correctly on a given host, for a given target.
configure
subsequently writes a configured `Makefile' from a
pre-built template; configure
uses variables that have been set in the
configuring process to determine the values of some variables in the
`Makefile'. Because of this we will refer to both configure
variables and `Makefile' variables. This convention allows us to
determine where the variable should be set initially, in either
`configure.in' or `Makefile.in'.
configure
really does
Cygnus configure
is a shell script that sets up an environment in
which your programs will compile correctly for your machine and
operating system, and will install in proper places. configure
accomplishes this task by doing the following:
configure
, either on the command line or in the
file `configure.in', which subsequently sets variables in each
generated `Makefile' to be used by make
when actually
building the software;
gdb
where to find the program's source code;
configure
finds another configure
script
further down in a given source tree, it knows to use this script and not
recur.
For the sake of safety (i.e., in order to prevent broken installations), the
GNU coding standards call for software to be configured in such a
way that an end user trying to build a given package will be able to do so by
affecting a finite number of variables. All GNU software comes with an
executable configure
shell script which sets up an environment within a
build directory which will correctly compile your new package for your host
(or, alternatively, whatever host you specify to configure
).
For further background on this topic, see On Configuring Development
Tools by K. Richard Pixley.
Use configure
to set for the build process:
configure
);
configure
);
configure
).
configure
uses a few other files to complete its tasks. These are
discussed in detail where noted.
configure.in
configure
. Shell script fragments reside here.
See section The configure.in
input file.
Makefile.in
configure
uses to build a file called `Makefile' in
the build directory. See section Makefile
generation.
config.sub
configure
to expand referents to the
hosttype argument into a single specification of the form
cpu-vendor-os. For instance, on the command line you can
specify
eg$ ./configure sun4to configure for a Sun SPARCstation running SunOS 4.x.
configure
consults config.sub
to find that the three-part specification for this
is
sparc-sun-sunos4.1.1which notes the cpu as `sparc', the manufacturer as `sun' (Sun Microsystems), and the os (operating system) as `sunos4.1.1', the SunOS 4.1.1 release. See section Variables available to
configure.in
.
config.guess
configure
uses the config.guess
shell script to make an
analysis of your machine (it assumes that you wish to configure your
software for the type of machine on which you are running). The output
of config.guess
is a three-part identifier as described above.
config.status
config.status
. The main purpose of this file is to allow the
`Makefile' for the current directory to rebuild itself, if
necessary. See section config.status
.
config/*
configure
uses three types of `Makefile' fragments, which
reside in the directory `srcdir/config/'. See section Adding information about local conventions.
There are several variables in the build process which you can control through
build programs such as make
. These include machine definitions, local
conventions, installation locations, locations for temporary files, etc. This
data is accessible through certain variables which are configurable in the
build process; we refer to them as build variables.
For lists of build variables which you can affect by using configure
,
see section Variables available to configure.in
,
and section Full descriptions of all installation subdirectories.
Generally, build variables, which are used by the `Makefile' to
determine various aspects of the build and installation processes, are
changeable with command-line options to configure
. In most large
suites of programs, like the Cygnus Support Developer's Kit, the
individual programs reside in several subdirectories of a single source
code "tree". All of these subdirectories need to be configured with
information relative to the build directory, which is not known
until configure
is run. Unless specified otherwise,
configure
recursively configures every subdirectory in the source
tree.
Build variables are passed from configure
directly into the
`Makefile', and use the same names (except that dashes are
transformed into underbars; for example, when you specify the option
`--exec-prefix' on the command line, the `Makefile' variable
`exec_prefix' is set). In other words, if you specify
eg$ ./configure --prefix=/usr/gnu/local ... hosttype
on the command line, configure
sets an variable called `prefix' to
`/usr/gnu/local', and passes this into the `Makefile' in the same
manner. After this command, each `Makefile' generated by configure
will contain a line that reads:
prefix = /usr/gnu/local
For a list of the `Makefile' variables configure
can change, and
instructions on how to change them, see section Variables available to configure.in
, and section Invoking configure
.
By default, configure
builds a `Makefile' and symbolic links in the
same directory as the source files. This default works for many cases, but it
has limitations. For instance, using this approach, you can only build object
code for one host at a time.
We refer to each directory where configure
builds a `Makefile' as
a build directory.
The build directory for any given build is always the directory from which you
call configure
, or `.' relative to your prompt. The default
source directory, the place configure
looks to find source code,
is also `.'. For instance, if we have a directory `/gnu-stuff/src/'
that is the top branch of a tree of GNU source code we wish to configure,
then the program we will use to configure this code is
`/gnu-stuff/src/configure', as follows. (Assume for the sake of argument
that our machine is a sun4.)
eg$ cd /gnu-stuff/src eg$ ./configure sun4 Created "Makefile" in /gnu-stuff/src eg$
We just configured the code in `/gnu-stuff/src' to run on a Sun SPARCstation using SunOS 4.x by creating a `Makefile' in `/gnu-stuff/src'. By default, we also specified that when this code is built, the object code should reside in the same directory, `/gnu-stuff/src'.
However, if we wanted to build this code for more than one host, we would be in
trouble, because the new configuration would write over the old one, destroying
it in the process. What we can do is to make a new build directory and
configure from there. Running configure
from the new directory will
place a correct `Makefile' and a `config.status' in this new file.
That is all configure
does; we must run make
to generate any
object code.
The new `Makefile' in `/gnu-stuff/sun4-obj', created from the template file `/gnu-stuff/src/Makefile.in', contains all the information needed to build the program.
eg$ mkdir /gnu-stuff/sun4-obj eg$ cd /gnu-stuff/sun4-obj eg$ ../src/configure --srcdir=../src sun4 Created "Makefile" in /gnu-stuff/sun4-obj eg$ ls Makefile config.status eg$ make all info install install-info clean compilation messages... eg$ mkdir /gnu-stuff/solaris2 eg$ cd /gnu-stuff/solaris2 eg$ ../src/configure --srcdir=../src sol2 Created "Makefile" in /gnu-stuff/solaris2 eg$ ls Makefile config.status eg$ make all info install install-info clean compilation messages...
We can repeat this for other configurations of the same software simply
by making a new build directory and reconfiguring from inside it. If
you do not specify the hosttype argument, configure
will attempt to figure out what kind of machine and operating system you
happen to be using. See section Determining system information. Of course, this may not always be the configuration you
wish to build.
Caution: If you build more than one configuration for a single program, remember that you must also specify a different `--prefix' for each configuration at configure-time. Otherwise, both configurations will be installed in the same default location (`/usr/local'); the configuration to be installed last would overwrite previously installed configurations.
Makefile
generation
Cygnus configure
creates a file called `Makefile' in the build
directory which can be used with make
to automatically build a given
program or package. configure
also builds a `Makefile' for each
relevant subdirectory for a given program or package (irrelevant subdirectories
would be those which contain no code which needs configuring, and which
therefore have no configure
input file `configure.in' and no
`Makefile' template `Makefile.in'). See section `How to Run make
' in GNU Make, for details on using
make
to compile your source code.
Each `Makefile' contains variables which have been configured for a
specific build. These build variables are determined when configure
is
run. All build variables have defaults. By default, configure
generates a `Makefile' which specifies:
make
.
Variables are changeable through command-line options to configure
(see section Invoking configure
).
If you are porting a new program and intend to use configure
, see
section Porting with configure
, as well as section `Writing Makefiles' in GNU Make, and section `Makefile Conventions' in GNU Coding Standards.
The shell script config.guess
is called when you do not specify a
hosttype on the command line to configure
. config.guess
acquires available system information from your local machine through the shell
command uname
. It compares this information to a database and attempts
to determine a usable three-part system identifier (known as a triple) to
use as your hosttype. See section What configure
really does, to see how this information is used.
Note: If you do not specify a hosttype on the command line,
configure
will attempt to configure your software to run on the machine
you happen to be using. This may not be the configuration you desire.
config.status
The final step in configuring a directory is to create an executable shell script, `config.status'. The main purpose of this file is to allow the `Makefile' for the current directory to rebuild itself, if necessary. It is usually run from within the `Makefile'. See section Extensions to the GNU coding standards.
`config.status' also contains a record of the configure
session
which created it.
configure.in
input file
A `configure.in' file for Cygnus configure
consists of a
per-invocation section, followed by a per-host section, followed by
a per-target section, optionally followed by a post-target section.
Each section is a shell script fragment, which is executed by the
configure
shell script at an appropriate time. Values are passed among
configure
and the shell fragments through a set of shell variables.
When each section is being interpreted by the shell, the shell's current
directory is the build directory, and any files created by the section (or
referred to by the section) will be relative to the build directory. To
reference files in other places (such as the source directory), prepend a shell
variable such as `$(srcdir)/' to the desired file name.
The beginning of the `configure.in' file begins the per-invocation section.
A line beginning with `# per-host:' begins the per-host section.
A line beginning with `# per-target:' begins the per-target section.
If it exists, the post-target section begins with `# post-target:'.
configure.in
The following variables pass information between the standard parts of
configure
and the shell-script fragments in `configure.in':
srctrigger
configure
tests to see that this file exists. If
the file does not exist, configure
prints an error message. This is
used as a sanity check that `configure.in' matches the source directory.
srcname
configure
uses the value of `srcname' when it prints the error
message.
configdirs
configure
should
recurse. You must usually set this in the per-invocation section of
`configure.in'.
If `Makefile.in' contains a line starting with `SUBDIRS =',
then it will be replaced with an assignment to `SUBDIRS' using
the value of `configdirs' (if `subdirs' is empty). This can
be used to determine which directories to configure and build depending
on the host and target configurations.
Use `configdirs' (instead of the `subdirs' variable
described below) if you want to be able to partition the
subdirectories, or use independent `Makefile' fragments.
Each subdirectory can be independent, and independently reconfigured.
subdirs
configure
should create a
`Makefile' (in addition to the current directory), without
recursively running configure
. Use `subdirs' (instead of the
`configdirs' variable described above) if you want to configure all of the
directories as a unit. Since there is a single invocation of configure
that configures many directories, all the directories can use the same
`Makefile' fragments, and the same configure.in
.
host
host_cpu
host_vendor
host_os
target
target_cpu
target_vendor
target_os
floating_point
configure
with the `--nfp'
command-line option, otherwise it is empty. This is a request to target
machines with no floating point unit, even if the targets ordinarily have
floating point units available.
gas
configure
with the
`--with-gnu-as' command line option, otherwise it is empty. This is a
request to assume that the specified hosttype machine has GNU as
available even if it ordinarily does not.
srcdir
package_makefile_frag
configure
will print a warning message. This
variable is not set by configure
.
host_makefile_frag
configure
will print a warning message. This
variable is not set by configure
.
target_makefile_frag
configure
will print a warning message.
This variable is not set by configure
.
site_makefile_frag
Makefile
removing
configure
is removing a configuration rather than creating
one.
files
links
configure
creates symbolic links with the first word of
`links' pointing to the first word of `files', the second word of
`links' pointing to the second word of `files', and so on.
configure.in
A minimal `configure.in' consists of four lines.
srctrigger=foo.c srcname="source for the foo program" # per-host: # per-target:
The `# per-host:' and `# per-target:' lines divide the file into the
three required sections. The `srctrigger' line names a file.
configure
checks to see that this file exists in the source directory
before configuring. If the `srctrigger' file does not exist,
configure
uses the value of `srcname' to print an error message
about not finding the source.
This particular example uses no links, and only the default host, target, and site-specific `Makefile' fragments if they exist.
configure
invokes the entire shell script fragment from the start of
`configure.in' up to a line beginning with `# per-host:'
immediately after parsing command line arguments. The variables
`srctrigger' and `srcname' must be set here.
You might also want to set the variables `configdirs' and `package_makefile_frag' here.
The per-host section of `configure.in' starts with the line that
begins with `# per-host:' and ends before a line beginning with
`# per-target:'. configure
invokes the commands in the
per-host section when determining host-specific information.
This section usually contains a big case
statement using the variable
`host' to determine appropriate values for `host_makefile_frag' and
`files', although `files' is not usually set here. Usually, it is
set at the end of the per-target section after determining the names of
the target specific configuration files.
The per-target section of `configure.in' starts with the line that
begins with `# per-target:' and ends before the line that begins with
`# post-target:', if there is such a line. Otherwise the
per-target section extends to the end of the file. configure
invokes the commands in the per-target section when determining
target-specific information, and before building any files, directories, or
links.
This section usually contains a big case
statement using the variable
`target' to determine appropriate values for `target_makefile_frag'
and `files'. The last lines in the per-target section normally set
the variables `files' and `links'.
The post-target section is optional. If it exists, the
`post-target' section starts with a line beginning with `#
Post-target:' and extends to the end of the file. If it exists,
configure
invokes this section once for each target after
building all files, directories, or links.
This section is seldom needed, but you can use it to edit the `Makefile'
generated by configure
.
configure.in
Here is a small example of a `configure.in' file.
# This file is a collection of shell script fragments # used to tailor a template configure script as # appropriate for this directory. For more information, # see configure.texi. configdirs= srctrigger=warshall.c srcname="bison" # per-host: case "${host}" in m88k-motorola-*) host_makefile_frag=config/mh-delta88 ;; esac # per-target: files="bison_in.hairy" links="bison.hairy" # post-target:
Using the default configuration, `make install' creates a single tree of files, some of which are programs. The location of this tree is determined by the value of the variable `prefix'. The default value of `prefix' is `/usr/local'. This is often correct for native tools installed on only one host.
In the default configuration, all files are installed in subdirectories
of `/usr/local'. The location is determined by the value of
the configure
variable `prefix'; in turn, this determines the
value of the `Makefile' variable of the same name (`prefix').
You can also set the value of the `Makefile' variable `prefix'
explicitly each time you invoke make
if you are so inclined. However,
because many programs have this location compiled in, you must specify the
`prefix' value consistently on each invocation of make
, or you will
end up with a broken installation.
To make this easier, the value of the configure
variable
`prefix' can be set on the command line to configure
using the option `--prefix='.
By default, host dependent files are installed in subdirectories of
`$(exec_prefix)'. The location is determined by the value of the
configure
variable `exec_prefix', which determines the value of the
`Makefile' variable `exec_prefix'. This makes it easier to install
for a single host, and simplifies changing the default location for the install
tree. The default doesn't allow for multiple hosts to effectively share
host independent files, however.
To configure so that multiple hosts can share common files, use something like:
configure host1 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1 make all info install install-info clean configure host2 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2 make all info install install-info
The first line configures the source for host1 to place host-specific programs in subdirectories of `/usr/gnu/H-host1'.
The second line builds and installs all programs for host1, including both host-independent and host-specific files, as well as removing the host-specific object files from of the build directory.
The third line reconfigures the source for host2 to place host specific programs in subdirectories of `/usr/gnu/H-host2'.
The fourth line builds and installs all programs for host2. Host specific files are installed in new directories, but the host independent files are installed on top of the host independent files installed for host1. This results in a single copy of the host independent files, suitable for use by both hosts.
See section Extensions to the GNU coding standards, for more information.
During any install, a number of standard directories are created. Their names
are determined by `Makefile' variables. Some of the defaults for
`Makefile' variables can be changed at configuration time using command
line options to configure
. For more information on the standard
directories or the `Makefile' variables, please refer to section `Makefile Conventions' in GNU Coding Standards. See also section Extensions to the GNU coding standards.
Note that configure
does not create the directory indicated by the
variable `srcdir' at any time. $(srcdir)
is not an installation
directory.
You can override all `Makefile' variables on the command line to
make
. (See section `Overriding Variables' in GNU Make.) If
you do so, you will need to specify the value precisely the same way for each
invocation of make
, or you risk ending up with a broken installation.
This is because many programs have the locations of other programs or files
compiled into them. If you find yourself overriding any of the variables
frequently, you should consider site dependent `Makefile' fragments. See
also section Adding site info.
During `make install', a number of standard directories are created and
populated. The following `Makefile' variables define them. Those whose
defaults are set by corresponding configure
variables are marked
"Makefile
and configure
".
prefix (Makefile
and configure
)
configure
(see section Invoking configure
). The default value
for `prefix' is `/usr/local'.
bindir
exec_prefix (Makefile
and configure
)
configure
.
(See section Invoking configure
.) The default value
for `exec_prefix' is `$(prefix)'.
libdir
mandir
man
format documentation ("man pages"). The default
value for `mandir' depends on `prefix'; `mandir' is normally
changed only indirectly through `prefix'. The default value for
`mandir' is `$(prefix)/man'.
manNdir
rcs
data file format). The default value for any of the
`manNdir' variables depends indirectly on `prefix', and is
normally changed only through `prefix'. The default value for
`manNdir' is `$(mandir)/manN'.
manNext
configure
. The GNU Coding
Standards do not call for `man1ext', `man2ext', so the intended use
for manext
is apparently not parallel to `mandir'. Its use is not
clear. (See also section Extensions to the GNU coding standards.)
infodir
info
format documentation. The default value for
`infodir' depends indirectly on `prefix'; `infodir' is
normally changed only through `prefix'. The default value for
`infodir' is `$(prefix)/info'.
docdir
info
or man
. The default value for `docdir' depends
indirectly on `prefix'; `docdir' is normally changed only through
`prefix'. The default value for `docdir' is `$(datadir)/doc'.
This variable is an extension to the GNU coding standards. (See
also section Extensions to the GNU coding standards.)
includedir
The arguments to configure
are hosttypes. By
hosttype we mean the environment in which the source will be
compiled. This need not necessarily be the same as the physical machine
involved, although it usually is.
For example, if some obscure machine had the GNU POSIX
emulation
libraries available, it would be possible to configure most GNU source for
a POSIX
system and build it on the obscure host.
For more on this topic, see section `Host Environments' in On Configuring Development Tools.
For building native development tools, or most of the other GNU tools, you need not worry about the target. The target of a configuration defaults to the same as the host.
For building cross development tools, please see section `Building Development Environments' in On Configuring Development Tools.
If you find that a tool does not get configured to your liking, or if
configure
's conventions differ from your local conventions, you should
probably consider site-specific `Makefile' fragments. See also
section Adding site info.
These are probably not the right choice for options that can be set from
the configure
command line or for differences that are host or
target dependent.
Cygnus configure
uses three types of `Makefile' fragments. In a
generated `Makefile' they appear in the order: target fragment,
host fragment, and site fragment. This allows host fragments to
override target fragments, and site fragments to override both.
Host-specific `Makefile' fragments conventionally reside in the `./config/' subdirectory with names of the form `mh-hosttype'. They are used for hosts that require odd options to the standard compiler and for compile time options based on the host configuration.
Target-specific `Makefile' fragments conventionally reside in the `./config/' subdirectory with names of the form `mt-target'. They are used for target dependent compile time options.
Site specific `Makefile' fragments conventionally reside in the
`./config/' subdirectory with names of the form `ms-site'.
They are used to override host- and target-independent compile time options.
Note that you can also override these options on the make
invocation
line.
The following additions to the GNU coding standards are required for
Cygnus configure
to work properly.
configure
, but they are documented here for
completeness.
install
make
would otherwise determine them to be out of
date. This can happen, for example, when the result of a `make all' is
transported via tape to another machine for installation.
clean
configure
. That is, make all clean
should return all directories
to their original condition. If this is not done, then the command sequence
configure host1 ; make all install clean ; configure host2 ; make all installwill fail because of intermediate files intended for host1.
configure
.
docdir
man
page or an info
file. For man
pages, see
`mandir'; for info
, see `infodir'.
includedir
gcc
include directory,
which is intended for gcc
only. Files in `includedir' may be used
by cc
as well.
ranlib
. Systems that do not use ranlib
can set `RANLIB'
to "echo
" in a host specific `Makefile' fragment.