README.rst 4.84 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
.. image:: https://travis-ci.org/bioidiap/bob.extension.svg?branch=master
André Anjos's avatar
André Anjos committed
6
   :target: https://travis-ci.org/bioidiap/bob.extension
André Anjos's avatar
André Anjos committed
7
8
.. image:: https://coveralls.io/repos/bioidiap/bob.extension/badge.png
   :target: https://coveralls.io/r/bioidiap/bob.extension
André Anjos's avatar
André Anjos committed
9
10
11
12
13
14
.. image:: http://img.shields.io/github/tag/bioidiap/bob.extension.png
   :target: https://github.com/bioidiap/bob.extension
.. image:: http://img.shields.io/pypi/v/bob.extension.png
   :target: https://pypi.python.org/pypi/bob.extension
.. image:: http://img.shields.io/pypi/dm/bob.extension.png
   :target: https://pypi.python.org/pypi/bob.extension
André Anjos's avatar
André Anjos committed
15

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

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

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

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

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

34
  from setuptools import dist
André Anjos's avatar
André Anjos committed
35
36
  dist.Distribution(dict(setup_requires=['bob.extension']))
  from bob.extension import Extension
37

38
39
40
  ...

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

André Anjos's avatar
André Anjos committed
42
    name="bob.myext",
43
44
45
46
    version="1.0.0",
    ...

    setup_requires=[
André Anjos's avatar
André Anjos committed
47
        'bob.extension',
48
49
50
51
        ],

    ...
    ext_modules=[
André Anjos's avatar
André Anjos committed
52
      Extension("bob.myext._myext",
53
        [
André Anjos's avatar
André Anjos committed
54
55
56
          "bob/myext/ext/file1.cpp",
          "bob/myext/ext/file2.cpp",
          "bob/myext/ext/main.cpp",
57
        ],
58
59
60
        packages = [ #pkg-config modules to append
          'blitz>=0.10',
          'bob-core',
61
62
          ],
        include_dirs = [ #optionally, include directories
André Anjos's avatar
André Anjos committed
63
          "bob/myext/ext/headers/",
64
          ],
65
66
67
68
69
70
71
72
        ),
      ... #add more extensions if you wish
    ],

    ...
    )

These modifications will allow you to compile extensions that are linked
73
74
against the named ``pkg-config`` modules. Other modules and options can be set
manually using `the standard options for python extensions
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``::

André Anjos's avatar
André Anjos committed
79
80
  [bob.myext]
  recipe = bob.buildout:develop
81
82
  verbose = true ;enables command-line verbosity
  debug = true ;compiles the module in debug mode
83
84
85
86
87
88

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
89

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

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.

98
99
Using the ``pkgconfig`` class
=============================
André Anjos's avatar
André Anjos committed
100
101
102
103
104
105

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
André Anjos's avatar
André Anjos committed
106
107
  dist.Distribution(dict(setup_requires='bob.extension'))
  from bob.extension.pkgconfig import pkgconfig
André Anjos's avatar
André Anjos committed
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

.. 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

128
129
130
131
132
133
134
135

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
André Anjos's avatar
André Anjos committed
136
137
  dist.Distribution(dict(setup_requires='bob.extension'))
  from bob.extension.boost import boost
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

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'
  >>> libpaths, libnames = boost.libconfig(['system', 'python'])
  >>> print(libpaths) # doctest: SKIP
  ['/usr/lib']
  >>> print(libnames) # doctest: SKIP
  ['boost_system-mt', 'boost_python-mt-py27']