README.rst 4.74 KB
Newer Older
André Anjos's avatar
André Anjos committed
1
2
3
4
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 30 Jan 08:46:53 2014 CET

André Anjos's avatar
André Anjos committed
5
6
.. image:: https://travis-ci.org/bioidiap/xbob.extension.svg?branch=prototype
   :target: https://travis-ci.org/bioidiap/xbob.extension
André Anjos's avatar
André Anjos committed
7
8
.. image:: http://img.shields.io/github/tag/bioidiap/xbob.extension.png
   :target: https://github.com/bioidiap/xbob.extension
André Anjos's avatar
André Anjos committed
9
.. image:: http://img.shields.io/pypi/v/xbob.extension.png
André Anjos's avatar
André Anjos committed
10
   :target: https://pypi.python.org/pypi/xbob.extension
André Anjos's avatar
André Anjos committed
11
.. image:: http://img.shields.io/pypi/dm/xbob.extension.png
André Anjos's avatar
André Anjos committed
12
   :target: https://pypi.python.org/pypi/xbob.extension
André Anjos's avatar
André Anjos committed
13

14
15
16
17
===========================================
 Python/C++ Bob Extension Building Support
===========================================

18
19
20
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.
21
22

Building with ``zc.buildout`` is possible using the ``develop`` recipe in
André Anjos's avatar
André Anjos committed
23
`xbob.buildout <http://pypi.python.org/pypi/xbob.buildout>`_. Follow the
24
instructions described on that package for this recipe.
25
26
27
28
29
30
31

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

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

32
33
  from setuptools import dist
  dist.Distribution(dict(setup_requires=['xbob.extension']))
34
  from xbob.extension import Extension
35

36
37
38
  ...

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

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
    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",
        ],
56
57
58
        packages = [ #pkg-config modules to append
          'blitz>=0.10',
          'bob-core',
59
60
61
62
          ],
        include_dirs = [ #optionally, include directories
          "xbob/myext/ext/headers/",
          ],
63
64
65
66
67
68
69
70
        ),
      ... #add more extensions if you wish
    ],

    ...
    )

These modifications will allow you to compile extensions that are linked
71
72
against the named ``pkg-config`` modules. Other modules and options can be set
manually using `the standard options for python extensions
73
74
75
76
77
78
<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
79
80
  verbose = true ;enables command-line verbosity
  debug = true ;compiles the module in debug mode
81
82
83
84
85
86

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
87

88
89
Python API to pkg-config and Boost
----------------------------------
André Anjos's avatar
André Anjos committed
90
91
92
93
94
95

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.

96
97
Using the ``pkgconfig`` class
=============================
André Anjos's avatar
André Anjos committed
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

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

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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'
143
144
145
  >>> libpaths, libnames = boost.libconfig(['system', 'python'])
  >>> print(libpaths) # doctest: SKIP
  ['/usr/lib']
146
147
  >>> print(libnames) # doctest: SKIP
  ['boost_system-mt', 'boost_python-mt-py27']