Enabled out-of-source build using BOB_BUILD_DIRECTORY environment variable.

README.rst

@@ -141,6 +141,16 @@ your ``buildout.cfg``. This includes, possibly, dependent projects. Currently,
 The recipe above creates a new interpreter that hooks that package in and
 builds the project considering variables like ``prefixes`` into consideration.
 
+By default, the extension code is compiled into a local directory called ``build``.
+This directory, after compilation, can be removed without issues, the resulting libraries will be copied into the package directories.
+To change the build directory of your package, and all other bob packages, you can define the ``BOB_BUILD_DIRECTORY`` environment variable, e.g.,::
+
+  $ python bootstrap.py
+  $ BOB_BUILD_DIRECTORY=/tmp/bob_build_dir ./bin/buildout
+
+Again, after successful compilation, this directory can be removed safely.
+
+
 Python API to pkg-config and Boost
 ----------------------------------
 

bob/extension/__init__.py

@@ -585,6 +585,14 @@ class build_ext(_build_ext):
   information.
   """
 
+  def finalize_options(self):
+    # check if the "BOB_BUILD_DIRECTORY" environment variable is set
+    _build_ext.finalize_options(self)
+    env = os.environ
+    if 'BOB_BUILD_DIRECTORY' in env:
+      self.build_temp = os.path.join(env['BOB_BUILD_DIRECTORY'], 'build_temp')
+      self.build_lib = os.path.join(env['BOB_BUILD_DIRECTORY'], 'build_lib')
+
   def run(self):
     """Iterates through the list of Extension packages and reorders them, so that the Library's come first
     """

doc/guide.rst

@@ -297,6 +297,38 @@ To avoid later complications, you should follow two guidelines for bob packages:
 The newly generated Library will be automatically linked to **all other** Extensions in the package.
 No worries, if the library is not used in the extension, the linker should be able to figure that out...
 
+.. note:
+  The clang linker seems not to be smart enough to detect unused libraries...
+
+
+Compiling your Library and Extension
+====================================
+
+To compile your C++ Python bindings and the pure C++ libraries, you can follow the same instructions as shown above:
+
+.. code-block:: sh
+
+  $ python bootstrap.py
+  ...
+  $ ./bin/buildout
+  ...
+
+This will automatically check out all required ``bob_packages`` and compile them locally.
+Afterwards, the C++ code from this package will be compiled, using a newly created ``build`` directory for temporary output.
+After compilation, this directory can be safely removed (re-compiling will re-create it).
+
+To get the source code compiled using another build directory, you can define a ``BOB_BUILD_DIRECTORY`` environment variable, e.g.:
+
+.. code-block:: sh
+
+  $ python bootstrap.py
+  ...
+  $ BOB_BUILD_DIRECTORY=/tmp/build_bob ./bin/buildout
+  ...
+
+The C++ code of this package, **and the code of all other** ``bob_packages`` will be compiled using the selected directory.
+Again, after compilation this directory can be safely removed.
+
 
 Documenting your C/C++ Python Extension
 =======================================