README.rst 5.12 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
7 8
.. image:: http://img.shields.io/badge/docs-latest-orange.png
   :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.extension/master/index.html
André Anjos's avatar
André Anjos committed
9 10
.. 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
11 12 13 14 15 16
.. 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
17

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

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

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

30 31
Further documentation on this package can be found `here <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.extension/master/index.html>`_.

32 33 34 35 36 37
Preparing for C++ Compilation
-----------------------------

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

38
  from setuptools import dist
André Anjos's avatar
André Anjos committed
39 40
  dist.Distribution(dict(setup_requires=['bob.extension']))
  from bob.extension import Extension
41

42 43 44
  ...

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

André Anjos's avatar
André Anjos committed
46
    name="bob.myext",
47 48 49 50
    version="1.0.0",
    ...

    setup_requires=[
André Anjos's avatar
André Anjos committed
51
        'bob.extension',
52 53 54 55
        ],

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

    ...
    )

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

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

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
92

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

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.

101 102
Using the ``pkgconfig`` class
=============================
André Anjos's avatar
André Anjos committed
103 104 105 106 107 108

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

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

131 132 133 134 135 136 137 138

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
139 140
  dist.Distribution(dict(setup_requires='bob.extension'))
  from bob.extension.boost import boost
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155

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']