README.rst 4.56 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>
.. Mon 03 Nov 2014 10:37:52 CET

André Anjos's avatar
André Anjos committed
5
6
7
=====
 Bob
=====
André Anjos's avatar
André Anjos committed
8
9
10
11
12
13
14
15
16

Bob is a free signal-processing and machine learning toolbox originally
developed by the Biometrics group at `Idiap`_ Research Institute, Switzerland.

The toolbox is written in a mix of `Python`_ and `C++`_ and is designed to be
both efficient and reduce development time. It is composed of a reasonably
large number of `packages`_ that implement tools for image, audio & video
processing, machine learning and pattern recognition.

André Anjos's avatar
André Anjos committed
17
18
**This package is only a place-holder for Bob's** `Wiki`_ **and** `Bug
tracker`_.
André Anjos's avatar
André Anjos committed
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

If just want to use Bob's functionalities on your experiments, you are **not**
supposed to install this package on your machine, but rather `create your own
personalised work environment
<https://github.com/idiap/bob/wiki/Installation>`_ depending on your needs, by
collecting individual subpackages based on your requirements.

If you are developing Bob packages which are supposed to built along side our
`nightly build system <https://www.idiap.ch/software/bob/buildbot/waterfall>`_,
please read on.

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

As per-usual, make sure all external `dependencies`_ are installed on your host
before trying to compile the whole of Bob. Once all dependencies_ are
satisified, you should be able to::

  $ python bootstrap.py
  $ ./bin/buildout

You may tweak the options in ``buildout.cfg`` to disable/enable verbosity and
André Anjos's avatar
André Anjos committed
41
debug builds, **before you run** ``./bin/buildout``.
André Anjos's avatar
André Anjos committed
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

Documentation
-------------

You can generate the documentation for all packages in this container, after
installation, using Sphinx::

  $ ./bin/sphinx-build . sphinx

This shall place in the directory ``sphinx``, the current version for the
documentation of the package.

Testing
-------

You can run a set of tests using the nose test runner::

  $ ./bin/nosetests -sv

You can run our documentation tests using sphinx itself::

  $ ./bin/sphinx-build -b doctest . sphinx

Adding a Package
----------------

.. warning::

   Before adding a package to this prototype, please ensure that the package:

   * contains a README clearly indicating how to install the package (including
     external dependencies required). Also, please add package badges for the
     build status and coverage as shown in other packages (even if your package
     is not yet integrated to Travis or Coveralls).

   * Has unit tests.

   * Is integrated with Travis-CI, and correctly tests on that platform (i.e.
     it builds, it tests fine and a documentation can be constructed and tested
     w/o errors)

   * Is integrated with Coveralls for reporting test coverage

   If you don't know how to do this, ask for information on the bob-devel
   mailing list.

Packages must be added using a git submodule::

  $ git submodule add https://github.com/bioidiap/bob.foo.bar.git layers/2/bob.foo.bar

Then, update the following files:

1. Add your package to the build::

   $ vim layer2.cfg

2. Add your package to the overall documentation::

   $ vim index.rst

3. Add your package to be "deploy-tested"::

   $ vim requirements2.txt

4. Add a row for your package in our Packages_ list

Updating a Package
------------------

Git submodules work by registering a precise commit hash identifier from each
submodule along with their repository locations. If you update the submodule,
you have to tell the main module that it now needs to use a new commit
identifier. If you don't do so, the main module will continue to checkout the
old version of the submodule.

In case a submodule is updated, this packagee will not automatically update its
reference to such database. You need to explicetly do it. To update a
submodule, first initialize this package::

  $ git submodule init
  $ git submodule update

Change to the directory where the submodule you want to update lives::

  $ cd layers/2/bob.foo.bar

The submodule repositories added by ``git submodule update`` are headless. This
means they don't have a branch. So, you must first checkout the branch with the
new revision you want to update::

  $ git checkout master
  $ git pull

Switch back to the root of the package and re-add the submodule::

  $ cd ../..
  $ git commit -m "Updated bob.foo.bar" layers/2/bob.foo.bar
  $ git push

.. External References

.. _c++: http://www2.research.att.com/~bs/C++.html
.. _python: http://www.python.org
.. _idiap: http://www.idiap.ch
.. _packages: https://github.com/idiap/bob/wiki/Packages
.. _wiki: https://github.com/idiap/bob/wiki
.. _bug tracker: https://github.com/idiap/bob/issues
.. _dependencies: https://github.com/idiap/bob/wiki/Dependencies