automake: VPATH Builds

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