README.rst 4.29 KB
Newer Older
André Anjos's avatar
André Anjos committed
1 2 3
.. image:: https://travis-ci.org/bioidiap/xbob.extension.svg?branch=prototype
   :target: https://travis-ci.org/bioidiap/xbob.extension

4 5 6 7
===========================================
 Python/C++ Bob Extension Building Support
===========================================

8 9 10
This package provides a simple mechanims for building Python/C++ extensions for
`Bob <http://www.idiap.ch/software/bob/>`_. You use this package by including
it in your ``setup.py`` file.
11 12

Building with ``zc.buildout`` is possible using the ``develop`` recipe in
André Anjos's avatar
André Anjos committed
13
`xbob.buildout <http://pypi.python.org/pypi/xbob.buildout>`_. Follow the
14
instructions described on that package for this recipe.
15 16 17 18 19 20 21

Preparing for C++ Compilation
-----------------------------

Creating C++/Python bindings should be trivial. Firstly, edit your ``setup.py``
so that you include the following::

22 23
  from setuptools import dist
  dist.Distribution(dict(setup_requires=['xbob.extension']))
24
  from xbob.extension import Extension
25

26 27 28
  ...

  setup(
André Anjos's avatar
André Anjos committed
29

30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
    name="xbob.myext",
    version="1.0.0",
    ...

    setup_requires=[
        'xbob.extension',
        ],

    ...
    ext_modules=[
      Extension("xbob.myext._myext",
        [
          "xbob/myext/ext/file1.cpp",
          "xbob/myext/ext/file2.cpp",
          "xbob/myext/ext/main.cpp",
        ],
46 47 48
        packages = [ #pkg-config modules to append
          'blitz>=0.10',
          'bob-core',
49 50 51 52
          ],
        include_dirs = [ #optionally, include directories
          "xbob/myext/ext/headers/",
          ],
53 54 55 56 57 58 59 60
        ),
      ... #add more extensions if you wish
    ],

    ...
    )

These modifications will allow you to compile extensions that are linked
61 62
against the named ``pkg-config`` modules. Other modules and options can be set
manually using `the standard options for python extensions
63 64 65 66 67 68
<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``::

  [xbob.myext]
  recipe = xbob.buildout:develop
69 70
  verbose = true ;enables command-line verbosity
  debug = true ;compiles the module in debug mode
71 72 73 74 75 76

If you need to build multiple eggs, you will need **one entry per project** on
your ``buildout.cfg``. This includes, possibly, dependent projects. Currently,
``zc.buildout`` ignores the ``setup_requires`` entry on your ``setup.py`` file.
The recipe above creates a new interpreter that hooks that package in and
builds the project considering variables like ``prefixes`` into consideration.
André Anjos's avatar
André Anjos committed
77

78 79
Python API to pkg-config and Boost
----------------------------------
André Anjos's avatar
André Anjos committed
80 81 82 83 84 85

This package alson contains a set of Pythonic bindings to the popular
pkg-config configuration utility. It allows distutils-based setup files to
query for libraries installed on the current system through that command line
utility.  library.

86 87
Using the ``pkgconfig`` class
=============================
André Anjos's avatar
André Anjos committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115

To use this package at your ``setup.py`` file, you will need to let distutils
know it needs it before importing it. You can achieve this with the following
trick::

  from setuptools import dist
  dist.Distribution(dict(setup_requires='xbob.extension'))
  from xbob.extension.pkgconfig import pkgconfig

.. note::

   In this case, distutils should automatically download and install this
   package on the environment it is required to setup other package.

After inclusion, you can just instantiate an object of type ``pkgconfig``::

  >>> zlib = pkgconfig('zlib')
  >>> zlib.version # doctest: SKIP
  1.2.8
  >>> zlib.include_directories() # doctest: SKIP
  ['/usr/include']
  >>> zlib.library_dirs # doctest: SKIP
  ['/usr/lib']
  >>> zlib > '1.2.6'
  True
  >>> zlib > '1.2.10'
  False

116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
Using the ``boost`` class
=========================

To use this package at your ``setup.py`` file, you will also need the same
trick as with ``pkgconfig``::

  from setuptools import dist
  dist.Distribution(dict(setup_requires='xbob.extension'))
  from xbob.extension.boost import boost

After inclusion, you can just instantiate an object of type ``boost``::

  >>> boost_pkg = boost('>= 1.47')
  >>> boost.version # doctest: SKIP
  1.50.0
  >>> boost.include_directory # doctest: SKIP
  '/usr/include'
133 134 135
  >>> libpaths, libnames = boost.libconfig(['system', 'python'])
  >>> print(libpaths) # doctest: SKIP
  ['/usr/lib']
136 137
  >>> print(libnames) # doctest: SKIP
  ['boost_system-mt', 'boost_python-mt-py27']