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

4
5
6
.. image:: http://img.shields.io/badge/docs-stable-yellow.png
   :target: http://pythonhosted.org/bob.buildout/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png
7
   :target: https://www.idiap.ch/software/bob/docs/latest/bob/bob.buildout/master/index.html
8
9
.. image:: https://gitlab.idiap.ch/bob/bob.buildout/badges/v2.0.16/build.svg
   :target: https://gitlab.idiap.ch/bob/bob.buildout/commits/v2.0.16
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
14
15
.. image:: http://img.shields.io/pypi/v/bob.buildout.png
   :target: https://pypi.python.org/pypi/bob.buildout
.. image:: http://img.shields.io/pypi/dm/bob.buildout.png
   :target: https://pypi.python.org/pypi/bob.buildout
André Anjos's avatar
André Anjos committed
16

André Anjos's avatar
André Anjos committed
17

André Anjos's avatar
André Anjos committed
18
19
20
===================================
 Buildout Recipes for Bob Packages
===================================
André Anjos's avatar
André Anjos committed
21

André Anjos's avatar
André Anjos committed
22
23
24
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
25

26

27
28
C++/Python Extension
--------------------
29

30
31
32
33
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
34
``bob.buildout:develop``, which should be considered deprecated.
35

André Anjos's avatar
André Anjos committed
36

37
38
39
Supported Options
=================

40
41
verbose

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

45
prefixes
46

André Anjos's avatar
André Anjos committed
47
48
  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
49
50
  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
51
52
  also sets, internally, ``PKG_CONFIG_PATH`` to a list of directories following
  where to search for pkg-config files.
53

54
55
56
debug

  If set, the module will be compiled with debugging symbols and with
André Anjos's avatar
André Anjos committed
57
58
59
60
  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.
61

André Anjos's avatar
André Anjos committed
62
environ
63

André Anjos's avatar
André Anjos committed
64
65
  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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
  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
84
  ``environ``'s ``BOB_PREFIX_PATH`` and ``PKG_CONFIG_PATH`` are **prepended**
André Anjos's avatar
André Anjos committed
85
  to those listed in ``prefixes``, if that is also set.
86

André Anjos's avatar
André Anjos committed
87

88
89
90
91
92
93
94
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
95
directories. If one or more are found, these paths are **prepended** into
96
97
the resulting scripts generated by this recipe and eggs will be searched on
those locations prioritarily.
98
99

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

102
103
python
  A pre-configured python interpreter
104

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

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

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

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

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
127
  recipe = bob.buildout:scripts
128

André Anjos's avatar
André Anjos committed
129

André Anjos's avatar
André Anjos committed
130
131
Common Supported Options
========================
132

133
The recipe supports the following options:
134

135
136
137
138
139
140
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.
141

142
143
144
145
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
146

147
148
149
150
151
152
153
154
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
155

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

160
161
162
163
164
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
165

André Anjos's avatar
André Anjos committed
166
167
Installation
------------
André Anjos's avatar
André Anjos committed
168

André Anjos's avatar
André Anjos committed
169
170
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
171

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

André Anjos's avatar
André Anjos committed
175

André Anjos's avatar
André Anjos committed
176
177
Contact
-------
178

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

André Anjos's avatar
André Anjos committed
182

André Anjos's avatar
André Anjos committed
183
184
185
186
.. 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