README.rst 3.44 KB
Newer Older
1
2
3
4
===========================================
 Python/C++ Bob Extension Building Support
===========================================

5
6
7
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.
8
9

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

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

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

19
20
  from setuptools import dist
  dist.Distribution(dict(setup_requires=['xbob.extension']))
21
  from xbob.extension import Extension
22

23
24
25
  ...

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

27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
    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",
        ],
43
44
45
        packages = [ #pkg-config modules to append
          'blitz>=0.10',
          'bob-core',
46
47
48
49
          ],
        include_dirs = [ #optionally, include directories
          "xbob/myext/ext/headers/",
          ],
50
51
52
53
54
55
56
57
        ),
      ... #add more extensions if you wish
    ],

    ...
    )

These modifications will allow you to compile extensions that are linked
58
59
against the named ``pkg-config`` modules. Other modules and options can be set
manually using `the standard options for python extensions
60
61
62
63
64
65
<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
66
67
  verbose = true ;enables command-line verbosity
  debug = true ;compiles the module in debug mode
68
69
70
71
72
73

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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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

Python API to pkg-config
------------------------

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.

Using at your ``setup.py``
==========================

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