automake-1.16: VPATH Builds
2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)
------------------------------------------------
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 (⇒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 ‘Makefile’s to allow these builds (⇒
‘VPATH’ Search Path for All Prerequisites (make)General Search.).
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.)
Info Catalog
automake-1.16: config
automake-1.16: Use Cases
automake-1.16: Two-Part Install