(automake-1.16.info)VPATH Builds

---

Next: Two-Part Install Prev: config.site Up: Use Cases

---

Enter node , (file) or (file)node

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 (Note: 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/’.

     ~ % 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 (Note:
‘VPATH’ Search Path for All Prerequisites.).

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