.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. 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/bioidiap/bob.buildout/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.buildout.svg?branch=v2.0.6
   :target: https://travis-ci.org/bioidiap/bob.buildout?branch=v2.0.6
.. image:: https://coveralls.io/repos/bioidiap/bob.buildout/badge.png?branch=v2.0.6
   :target: https://coveralls.io/r/bioidiap/bob.buildout?branch=v2.0.6
.. image:: https://img.shields.io/badge/github-master-0000c0.png
   :target: https://github.com/bioidiap/bob.buildout/tree/master
.. 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 contains a number of recipes to be used to build `Satellite
Packages <http://www.idiap.ch/software/bob/docs/releases/last/sphinx/html/OrganizeYourCode.html>`_ for `Bob <http://idiap.github.com/bob/>`_,
a signal-processing and machine learning toolbox originally developed by the
Biometrics Group at Idiap, in Switzerland.

.. note::

  You normally don't need to download this package directly. It will be done by
  ``zc.buildout`` automatically, if you followed our recipe to build `Satellite
  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.

Other Recipes
-------------

This package also provides recipes that allow for the discrete installation of
interpreters and support programs, lumped together with the ``scripts`` recipe
described above. You can use some of the options described above with these
recipes. For example, the ``prefixes``, ``eggs`` and ``extra-paths`` are
considered by all these recipes.

.. note::

  Use of these individual recipes should be done with care. The ``scripts``
  recipe should be used by default, unless you have a special requirement that
  is not covered by that recipe.

python
  This recipe generates **just** a python interpreter on the binary directory.
  Extra options considered: ``interpreter``.

ipython
  This recipe generates an IPython interpreter on the binary directory.
  Extra options considered: ``interpreter``.

gdb-python
  This recipe generates a gdb launcher using the python interpreter so you can
  start your scripts directly typing ``gdb-python myscript.py``.

pylint
  No extra options for this recipe.

nose
  This recipe generates only the ``nosetests`` program. Extra options
  considered are:``nose-flags``.

coverage
  This recipe generates only the ``coverage`` program. Extra options
  considered are:``coverage-flags``.

sphinx
  This recipe generates only the Sphinx documentation generator applications.
  Extra options considered: none.

egg.scripts
  This recipe generates only the scripts (and dependent scripts) for the
  package. Extra options considered: ``dependent-scripts``.
