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