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
7
.. 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
8
9
10
.. image:: http://img.shields.io/github/tag/bioidiap/xbob.extension.svg
   :target: https://github.com/bioidiap/xbob.extension

André Anjos's avatar
André Anjos committed
11
.. image:: http://img.shields.io/pypi/v/xbob.extension.svg
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

.. image:: http://img.shields.io/pypi/dm/xbob.extension.svg
André Anjos's avatar
André Anjos committed
15
   :target: https://pypi.python.org/pypi/xbob.extension
André Anjos's avatar
André Anjos committed
16

17
18
19
20
===========================================
 Python/C++ Bob Extension Building Support
===========================================

21
22
23
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.
24
25

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

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

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

35
36
  from setuptools import dist
  dist.Distribution(dict(setup_requires=['xbob.extension']))
37
  from xbob.extension import Extension
38

39
40
41
  ...

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

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

    ...
    )

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

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
90

91
92
Python API to pkg-config and Boost
----------------------------------
André Anjos's avatar
André Anjos committed
93
94
95
96
97
98

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.

99
100
Using the ``pkgconfig`` class
=============================
André Anjos's avatar
André Anjos committed
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
126
127
128

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

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