
The default build of GNU APL creates only the APL interpreter binary
aka. src/apl. This is assumed to be what the majority of GNU APL users
need in the first place.

This default build places all intermediate files - mostly .o files
from the corresponding .cc files into the same directory (src) as
the source files. If GNU APL is re-configured after the first build,
the intermediate files from the previous build are overwritten with
- possibly different - intermediate files having the same names and
this can, depending on the ./configure options that were used, lead to
a dubious mix of object files built with different ./configure options.

Also, if the same target, say src/apl, is built several times with
different ./configure options then the previous src/apl versions are
lost and the user has to (manually) copy them to some other place where
they are not overwritten.

To avoid the above complications, GNU APL supports the so-called
"VPATH builds", which are a feature of the Autoconf build system used
by GNU APL.

The difference between the default build and a VPATH build is this: the
default build places all object files and the final result (i.e. file apl,
libapl.so, or lib_gnu_apl.so) into the sub-directory src of the top-level
directory, while a VPATH build places these files into a sub-directory
chosen (and created) by the user. As a consequence, if a user wants to
build different configurations in one go (i.e. without the need to copy
the build results between different builds) then she can do so by creating
different directories for the different builds and then executing the
build in the different directories. The total build time increases a little
because every object file is recompiled in every build while some of
them may be re-used in a standard build.

A VPATH build is, in principle, performed like this:

    cd <top-level-apl-directory>
    mkdir my_build_directory
    cd my_build_directory
    ../configure
    make

However, the following considerations are required:

A. the build directory chosen for the VPATH build needs to be located below
   the top-level APL directory and (currently) not deeper than four directory
   levels. A commom choice is a directory named 'obj' in the top-level
   directory.

B. The top-level APL directory and its sub-directory 'src' must be "fresh",
   i.e. must not have been polluted by non-VPATH builds before a VPATH
   build. A prior non-VPATH build will cause the subsequent VPATH build to
   (incorrectly) "believe" that the object files in the 'src' directory (from
   the non-VPATH build) need not be recompiled (even though these files
   should now be in the 'src' directory of the VPATH build directory.

   The following "hack" to fix a polluted top-level directory seems work:

   cd <top-level-apl-directory>
   ./configure         # so that src/Makefile exists
   make -C src clean   # otherwise some object files will be missing
   rm config.status    # otherwise configure will complain

   After a previous (non-VPATH) ./configure (in the top-level GNU APL
   directory) the same can be achieved with 'make VPATH_clean'

An example for VPATH builds is the script build/build_all
