Commit 4ed14883 authored by Manuel Günther's avatar Manuel Günther
Browse files

Added documentation in README.

parent fa02136a
......@@ -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
......
......@@ -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):
......
......@@ -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))
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment