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.

The source tree is rooted in the directory containing
configure. It contains all the sources files (those that are
distributed), and may be arranged using several subdirectories.

The build tree is rooted in the directory in which 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 build
everything in a subdirectory called build/.

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:

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.

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-ROM with unpacked source code, before the GNU
project grew so big.)