README.rst 6.75 KB
Newer Older
1
2
3
.. vim: set fileencoding=utf-8 :
.. Thu 30 Jan 08:46:53 2014 CET

4
.. image:: http://img.shields.io/badge/docs-stable-yellow.png
5
   :target: https://www.idiap.ch/software/bob/docs/bob/bob.buildout/stable/index.html
6
.. image:: http://img.shields.io/badge/docs-latest-orange.png
7
   :target: https://www.idiap.ch/software/bob/docs/bob/bob.buildout/master/index.html
8
9
.. image:: https://gitlab.idiap.ch/bob/bob.buildout/badges/master/build.svg
   :target: https://gitlab.idiap.ch/bob/bob.buildout/commits/master
André Anjos's avatar
André Anjos committed
10
11
.. image:: https://img.shields.io/badge/gitlab-project-0000c0.svg
   :target: https://gitlab.idiap.ch/bob/bob.buildout
André Anjos's avatar
André Anjos committed
12
13
.. image:: http://img.shields.io/pypi/v/bob.buildout.png
   :target: https://pypi.python.org/pypi/bob.buildout
André Anjos's avatar
André Anjos committed
14

André Anjos's avatar
André Anjos committed
15

André Anjos's avatar
André Anjos committed
16
17
18
===================================
 Buildout Recipes for Bob Packages
===================================
André Anjos's avatar
André Anjos committed
19

André Anjos's avatar
André Anjos committed
20
21
22
This package is part of the signal-processing and machine learning toolbox
Bob_. It contains a number of ``zc.buildout`` recipes for simplifying builds of
Bob_ packages.
André Anjos's avatar
André Anjos committed
23

24

25
26
C++/Python Extension
--------------------
27

28
29
30
31
This extension allows you to compile C/C++ extensions that depend on each other
using a buildout. It assures that eggs living in both ``develop-eggs`` and
``eggs`` are on your path before building the packages in the ``develop``
section. By using this extension you can drop the use of the local recipe
André Anjos's avatar
André Anjos committed
32
``bob.buildout:develop``, which should be considered deprecated.
33

André Anjos's avatar
André Anjos committed
34

35
36
37
Supported Options
=================

38
39
verbose

André Anjos's avatar
André Anjos committed
40
41
  If set, buildout it will output the compilation commands while compiling the
  module.
42

43
prefixes
44

André Anjos's avatar
André Anjos committed
45
46
  A list of directories where this recipe will look for installed software,
  such as compiled libraries and header files. It is the same as setting the
47
48
  environment variable ``BOB_PREFIX_PATH`` to a list of paths containing
  externally installed software. As a side-effect, setting ``BOB_PREFIX_PATH``
André Anjos's avatar
André Anjos committed
49
50
  also sets, internally, ``PKG_CONFIG_PATH`` to a list of directories following
  where to search for pkg-config files.
51

52
53
54
debug

  If set, the module will be compiled with debugging symbols and with
André Anjos's avatar
André Anjos committed
55
56
57
58
  optimization turned off. If ``debug`` is set to ``true``, this is equivalent
  to appending the environment variables ``CFLAGS`` and ``CXXFLAGS`` with ``-O0
  -g``. If it is set to ``false``, it is the same as appending ``-O3 -g0``
  instead.
59

André Anjos's avatar
André Anjos committed
60
environ
61

André Anjos's avatar
André Anjos committed
62
63
  The name of a section on your configuration file that contains the names and
  values of environment variables that should be used through the build. This
André Anjos's avatar
André Anjos committed
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
  section is named, by default, ``environ``.

  If a section named ``environ`` exists, it is read and the environment
  variables are set **before** the specified eggs are developed. You can use
  variable substitution on this section. Here is an an example::

    [environ]
    CFLAGS = '-O0 -g -DNDEBUG'
    CXXFLAGS = ${CFLAGS}

  Notice there is some functionality overlap between the previous flags and the
  use of section ``environ``. While it is more flexible, you must understand
  the consequences of setting both ``prefixes`` and ``debug``, together with
  ``environ``. The rule is simple: values set on the ``environ`` section have
  **precedence** to ``debug`` and ``prefixes``. If you set ``debug`` and
  ``CFLAGS`` (or ``CXXFLAGS``) in the ``environ`` section, for example, then
  the values on the final ``CFLAGS`` variable would be ``-O0 -g`` followed by
  ``environ``'s ``CFLAGS`` settings. Analogously, the paths defined by
82
  ``environ``'s ``BOB_PREFIX_PATH`` and ``PKG_CONFIG_PATH`` are **prepended**
André Anjos's avatar
André Anjos committed
83
  to those listed in ``prefixes``, if that is also set.
84

André Anjos's avatar
André Anjos committed
85

86
87
88
89
90
91
92
Multi-Script Installer
----------------------

This recipe installs **all** most used scripts and interpreter proxies for your
package. It will look at the ``buildout`` section entry called ``prefixes``,
that potentially lists prefixes that should be **prepended** to the default
python environment. In these prefixes, it will look for standard python
93
directories. If one or more are found, these paths are **prepended** into
94
95
the resulting scripts generated by this recipe and eggs will be searched on
those locations prioritarily.
96
97

By default, this recipe will use the eggs defined at the ``buildout`` section
98
called ``eggs``, but that can be overriden locally. It generates these scripts:
99

100
101
python
  A pre-configured python interpreter
102

André Anjos's avatar
André Anjos committed
103
104
105
gdb-python
  A pre-configured python interpreter, prefixed with ``gdb`` to make debugging
  easier. Use it like you use ``python``.
106

107
nosetests
André Anjos's avatar
André Anjos committed
108
109
  A test runner called ``nosetests`` will be created on the bin directory of
  buildout.
110

111
112
113
114
coverage
  A test coverage application called ``coverage`` will be created on the bin
  directory of buildout.

André Anjos's avatar
André Anjos committed
115
116
sphinx
  Several sphinx utilities will be created on the bin directory of buildout.
117
118
119
120
121
122
123
124

package scripts
  Package scripts will be created taking into account the ``prefixes``
  established for this section or globally (as a second priority).

To use this recipe, you just have to simply do::

  [scripts]
André Anjos's avatar
André Anjos committed
125
  recipe = bob.buildout:scripts
126

André Anjos's avatar
André Anjos committed
127

André Anjos's avatar
André Anjos committed
128
129
Common Supported Options
========================
130

131
The recipe supports the following options:
132

133
134
135
136
137
138
prefixes
  A list of directories where this recipe will look for subdirectories with
  the stem ``lib/python*/site-packages``. All directories matching this
  condition are appended to the search paths. If not given, the value of this
  property defaults to ``buildout.prefixes``. Both can be empty, which makes
  this recipe default to using standard available paths.
139

140
141
142
143
eggs
  The eggs option specifies a list of eggs to use for **building** this
  package. Each string must be given on a separate line. If not given, the
  value of this property defaults to ``buildout.eggs``.
André Anjos's avatar
André Anjos committed
144

145
146
147
148
149
150
151
152
dependent-scripts
  If set to the string ``true``, scripts will be generated for all required
  eggs in addition to the eggs specifically named.

interpreter
  The name of a script to generate that allows access to a Python interpreter
  that has the path set based on the eggs installed. If you don't specify
  anything, the default value ``python`` will be used.
André Anjos's avatar
André Anjos committed
153

154
155
156
157
extra-paths
  Extra paths to be appended in a generated script. To prepend, using the
  ``prefixes`` entry.

158
159
160
161
162
nose-flags
  These are extra flags that are **appended** to the given ``nosetests``
  command line, automatically. Use this to preset arguments you like running
  all the time like ``-v``, for example.

André Anjos's avatar
André Anjos committed
163

André Anjos's avatar
André Anjos committed
164
165
Installation
------------
André Anjos's avatar
André Anjos committed
166

André Anjos's avatar
André Anjos committed
167
168
Follow our `installation`_ instructions. Then, using the Python interpreter
provided by the distribution, bootstrap and buildout this package::
André Anjos's avatar
André Anjos committed
169

André Anjos's avatar
André Anjos committed
170
171
  $ python bootstrap-buildout.py
  $ ./bin/buildout
172

André Anjos's avatar
André Anjos committed
173

André Anjos's avatar
André Anjos committed
174
175
Contact
-------
176

André Anjos's avatar
André Anjos committed
177
178
For questions or reporting issues to this software package, contact our
development `mailing list`_.
179

André Anjos's avatar
André Anjos committed
180

André Anjos's avatar
André Anjos committed
181
182
183
184
.. Place your references here:
.. _bob: https://www.idiap.ch/software/bob
.. _installation: https://gitlab.idiap.ch/bob/bob/wikis/Installation
.. _mailing list: https://groups.google.com/forum/?fromgroups#!forum/bob-devel