The GNU Build System distinguishes two trees: the source tree, and the build tree. These are two directories that may be the same, or different.
The source tree is rooted in the directory containing the configure script. It contains all the source files (those that are distributed), and may be arranged using several subdirectories.
The build tree is rooted in the current directory at the time configure was run, and is populated with all object files, programs, libraries, and other derived files built from the sources (and hence not distributed). The build tree usually has the same subdirectory layout as the source tree; its subdirectories are created automatically by the build system.
If configure is executed in its own directory, the source and build trees are combined: derived files are constructed in the same directories as their sources. This was the case in our first installation example (see Basic Installation).
A common request from users is that they want to confine all derived files to a single directory, to keep their source directories uncluttered. Here is how we could run configure to create everything in a build tree (that is, subdirectory) called build/.
~ % tar zxf ~/amhello-1.0.tar.gz ~ % cd amhello-1.0 ~/amhello-1.0 % mkdir build && cd build ~/amhello-1.0/build % ../configure ... ~/amhello-1.0/build % make ...
These setups, where source and build trees are different, are often
called parallel builds or VPATH builds. The expression
parallel build is misleading: the word parallel is a
reference to the way the build tree shadows the source tree, it is not
about some concurrency in the way build commands are run. For this
reason we refer to such setups using the name VPATH builds in
the following. VPATH is the name of the make feature
used by the Makefiles to allow these builds (see VPATH Search Path for All Prerequisites in The
GNU Make Manual).
VPATH builds have other interesting uses. One is to build the same sources with multiple configurations. For instance:
~ % tar zxf ~/amhello-1.0.tar.gz ~ % cd amhello-1.0 ~/amhello-1.0 % mkdir debug optim && cd debug ~/amhello-1.0/debug % ../configure CFLAGS='-g -O0' ... ~/amhello-1.0/debug % make ... ~/amhello-1.0/debug % cd ../optim ~/amhello-1.0/optim % ../configure CFLAGS='-O3 -fomit-frame-pointer' ... ~/amhello-1.0/optim % make ...
With network file systems, a similar approach can be used to build the
same sources on different machines. For instance, suppose that the
sources are installed on a directory shared by two hosts: HOST1
and HOST2, which may be different platforms.
~ % cd /nfs/src /nfs/src % tar zxf ~/amhello-1.0.tar.gz
On the first host, you could create a local build directory:
[HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure ... [HOST1] /tmp/amh % make && sudo make install ...
(Here we assume that the installer has configured sudo so it
can execute make install with root privileges; it is more convenient
than using su like in Basic Installation).
On the second host, you would do exactly the same, possibly at the same time:
[HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure ... [HOST2] /tmp/amh % make && sudo make install ...
In this scenario, nothing forbids the /nfs/src/amhello-1.0 directory from being read-only. In fact VPATH builds are also a means of building packages from a read-only medium such as a CD-ROM. (The FSF used to sell CD-ROMs with unpacked source code, before the GNU project grew so big.)