Added documentation in README.

README.rst

@@ -37,7 +37,7 @@ so that you include the following::
 
   from setuptools import dist
   dist.Distribution(dict(setup_requires=['bob.extension']))
-  from bob.extension import Extension
+  from bob.extension import Extension, Library, build_ext
 
   ...
 
@@ -61,23 +61,74 @@ so that you include the following::
         ],
         packages = [ #pkg-config modules to append
           'blitz>=0.10',
-          ],
+        ],
+        bob_packages = [ #optionally, bob C++ modules to import
+          "bob.core"
+        ],
         include_dirs = [ #optionally, include directories
           "bob/myext/ext/headers/",
-          ],
-        ),
+        ],
+      ),
       ... #add more extensions if you wish
     ],
 
+    cmdclass = {
+      'build_ext': build_ext
+    },
+
     ...
-    )
+  )
 
 These modifications will allow you to compile extensions that are linked
 against the named ``pkg-config`` modules. Other modules and options can be set
 manually using `the standard options for python extensions
-<http://docs.python.org/2/extending/building.html>`_. To hook-in the building
-on the package through ``zc.buildout``, add the following section to your
-``buildout.cfg``::
+<http://docs.python.org/2/extending/building.html>`_.
+
+Adding pure C++ libraries
+-------------------------
+
+Most of the bob packages will include pure C++ code that can be used in other packages.
+When your package should export a library with pure C++ code as well, you can build it with the ``Library`` extension.
+You can simply add this ``Library`` to the list of ``ext_modules`` as follows::
+
+  setup(
+    ...
+    ext_modules=[
+      Library("bob_myext",
+        [
+          "bob/myext/ext/cpp/cppfile1.cpp",
+          "bob/myext/ext/cpp/cppfile2.cpp",
+        ],
+        package_directory = os.path.dirname(os.path.realpath(__file__)),
+        target_directory = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'bob', 'myext'),
+        version = "1.0.0",
+        bob_packages = [...],
+        packages = [...],
+        ...
+      ),
+      Extension("bob.my_ext._myext",
+        ...
+        libraries = ["bob_myext",...]
+      )
+    ],
+
+    cmdclass = {
+      'build_ext': build_ext
+    },
+
+    ...
+  )
+
+This will compile the given source files of the library using `CMake <http://www.cmake.org>`_.
+Please assure that the name of the library ``bob_myext`` is compatible with your package name so that the library can be imported in other packages using the ``bob_packages`` list.
+
+Also, it is assumed that **all** header files that are exported by the C++ library are listed in the *bob/myext/include* directory.
+This directory is automatically added to the list of include directories -- in your own package and in all other packages that use the ``bob_packages`` list.
+
+Compiling the module
+--------------------
+
+To hook-in the building on the package through ``zc.buildout``, add the following section to your ``buildout.cfg``::
 
   [bob.myext]
   recipe = bob.buildout:develop

bob/extension/__init__.py

@@ -467,7 +467,7 @@ class Library (Extension):
     # find the cmake executable
     cmake = find_executable("cmake")
     if not cmake:
-      raise IOError("The Library class needs CMake version >= 2.8 to be installed, but CMake cannot be found")
+      raise OSError("The Library class needs CMake version >= 2.8 to be installed, but CMake cannot be found")
     self.c_cmake = cmake[0]
 
     # call base class constructor, i.e., to handle the packages
@@ -507,9 +507,11 @@ class Library (Extension):
       env['CXX'] = compiler
     # configure cmake
     command = [self.c_cmake, self.c_package_directory, '-DCMAKE_BUILD_TYPE=%s' % build_type]
-    subprocess.call(command, cwd=build_directory, env=env)
+    if subprocess.call(command, cwd=build_directory, env=env) != 0:
+      raise OSError("Could not generate makefiles with CMake")
     # run make
-    subprocess.call(['make'], cwd=build_directory, env=env)
+    if subprocess.call(['make'], cwd=build_directory, env=env) != 0:
+      raise OSError("CMake compilation stopped with an error; stopping ...")
 
 
 class build_ext(_build_ext):

bob/extension/cmake.py

@@ -70,11 +70,30 @@ class CMakeListsGenerator:
 
     Keyword parameters:
 
-    name
+    name : string
       The name of the library to generate
 
+    sources : [string]
+      The list of source files that should be compiled with CMake
+
+    target_directory : [string]
+      The directory where the final library should be placed
+
     version
       The version of the library, major.minor.patch
+
+    include_directories : [string]
+      A list of include directories required to compile the ``sources``
+
+    libraries : [string]
+      A list of libraries to be linked into the generated library
+
+    library_directories : [string]
+      A list of directories, where the ``libraries`` can be found.
+      Note that the order of this list might be important.
+
+    macros : [(string, string)]
+      A list of preprocessor defines ``name=value`` that will be added to the compilation
     """
 
     self.name = name
@@ -106,8 +125,8 @@ class CMakeListsGenerator:
         f.write('add_definitions(-D%s=%s)\n' % macro)
       # compile this library
       f.write('\nadd_library(${PROJECT_NAME} \n\t' + "\n\t".join(self.sources) + '\n)\n')
-      f.write('set_target_properties(${PROJECT_NAME} PROPERTIES POSITION_INDEPENDENT_CODE TRUE SOVERSION "%s" VERSION "%s")\n\n' % (self.version.split('.')[0], '.'.join(self.version.split('.')[:2])))
-      f.write('set_target_properties(${PROJECT_NAME} PROPERTIES LIBRARY_OUTPUT_DIRECTORY %s)\n' % self.target_directory)
+      f.write('set_target_properties(${PROJECT_NAME} PROPERTIES POSITION_INDEPENDENT_CODE TRUE SOVERSION "%s" VERSION "%s")\n' % (self.version.split('.')[0], '.'.join(self.version.split('.')[:2])))
+      f.write('set_target_properties(${PROJECT_NAME} PROPERTIES LIBRARY_OUTPUT_DIRECTORY %s)\n\n' % self.target_directory)
       # link libraries
       if self.libraries:
         f.write('target_link_libraries(${PROJECT_NAME} %s)\n\n' % " ".join(self.libraries))