README.rst

.. vim: set fileencoding=utf-8 :
.. Thu 30 Jan 08:46:53 2014 CET

.. 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
   :target: https://www.idiap.ch/software/bob/docs/latest/bob/bob.buildout/master/index.html
.. image:: https://gitlab.idiap.ch/bob/bob.buildout/badges/master/build.svg
   :target: https://gitlab.idiap.ch/bob/bob.buildout/commits/master
.. image:: https://img.shields.io/badge/gitlab-project-0000c0.svg
   :target: https://gitlab.idiap.ch/bob/bob.buildout
.. 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


===================================
 Buildout Recipes for Bob Packages
===================================

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.


C++/Python Extension
--------------------

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
``bob.buildout:develop``, which should be considered deprecated.


Supported Options
=================

verbose

  If set, buildout it will output the compilation commands while compiling the
  module.

prefixes

  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
  environment variable ``BOB_PREFIX_PATH`` to a list of paths containing
  externally installed software. As a side-effect, setting ``BOB_PREFIX_PATH``
  also sets, internally, ``PKG_CONFIG_PATH`` to a list of directories following
  where to search for pkg-config files.

debug

  If set, the module will be compiled with debugging symbols and with
  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.

environ

  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
  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
  ``environ``'s ``BOB_PREFIX_PATH`` and ``PKG_CONFIG_PATH`` are **prepended**
  to those listed in ``prefixes``, if that is also set.


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
directories. If one or more are found, these paths are **prepended** into
the resulting scripts generated by this recipe and eggs will be searched on
those locations prioritarily.

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

python
  A pre-configured python interpreter

gdb-python
  A pre-configured python interpreter, prefixed with ``gdb`` to make debugging
  easier. Use it like you use ``python``.

nosetests
  A test runner called ``nosetests`` will be created on the bin directory of
  buildout.

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

sphinx
  Several sphinx utilities will be created on the bin directory of buildout.

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


Common Supported Options
========================

The recipe supports the following options:

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.

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

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.

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

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.


Installation
------------

Follow our `installation`_ instructions. Then, using the Python interpreter
provided by the distribution, bootstrap and buildout this package::

  $ python bootstrap-buildout.py
  $ ./bin/buildout


Contact
-------

For questions or reporting issues to this software package, contact our
development `mailing list`_.


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