About Bitten
============

Bitten is a simple distributed continuous integration system that not only
coordinates builds across multiple machines, but also collects software
metrics generated by builds, to enable feedback and reporting about
the progress of a software project.

The Bitten software consists of three separate parts:
 * The build slave, which executes build on behalf of a local or remote
   build master
 * The build master, which orchestrate builds for a project across all
   connected slaves, and stores the build status and results to the
   database
 * The web interface, which is implemented as an add-on to Trac
   (http://trac.edgewall.com/) and provides a build management interface
   as well as presentation of build results.

Both the build master and the web interface depend on Trac 0.9 beta 1, and
need to be installed on the same machine, together with the Subversion
repository. The build slave only requires Python (>= 2.3) as well as the
tools required by the build process itself. A build slave may be run on
any machine that can connect to the server running the Bitten build master.


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

Bitten is written in Python, so make sure that you have Python installed.
Also, make sure that the version of Python you have installed is 2.3 or
later.

If that's taken care of, you just need to download and unpack the Bitten
distribution, and execute the command:

  $ python setup.py install

from the top of the directory where you unpacked (or checked out) the Bitten
code. Note that you may need administrator/root privileges for this step, as
it will attempt to install Bitten to the Python site-packages directory on
your system.

It's also a good idea to run the unit tests at this point, to make sure that
the code works as expected on your platform:

  $ python setup.py test


What's left to do now depends on whether you want to use the build master and
web interface, or just the build slave. In the latter case, you're already
done. You might need to install software that the build of your project
requires, but the Bitten build slave itself doesn't require anything extra.

For the build master and web interface, you'll need to install Trac 0.9
beta 1 and Berkeley DB XML >= 2.1.x, as well as their respective
dependencies. Please refer to the documentation of those projects for
information how they are installed.


Build Master Configuration
--------------------------

Once Bitten, Trac and BDB XML are installed and working, you'll have to
introduce Bitten to your Trac project environment. If you don't have a 
Trac project set up yet, you'll need to do so in order to use Bitten.

If you already have a Trac project environment, the Trac web interface
will inform you with an error message that the environment needs to be
upgraded. To do this, run:

  $ trac-admin /path/to/projenv upgrade

This will create the database tables and directories that Bitten requires.
You probably also want to grant permissions to someone (such as yourself)
to manage build configurations, and allow anonymous users to view the
status and results of builds:

  $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
  $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN

You should now see an additional tab labelled "Build Status" in the Trac
navigation bar. This link will take you to the list of build configurations,
which at this point is of course empty. If you've set up permissions
correctly as described previously, you should see a button for adding new
build configurations. Click that button and fill out the form. Also, add
at least one target platform after saving the configuration. Last but not
least, you'll have to "active" the build configuration.


Running the Build Master
------------------------

At this point, you're ready to start the Bitten build master. The
installation of Bitten should have put a `bittend` script on your path.
If the script is not on your path, look for it in the `bin` or `scripts`
subdirectory of your Python installation.

To find out about the options and arguments of the script, execute it with
the `--help` option as follows:

  $ bittend --help

Most commonly, you'll want to specify the log level and log file, as well as
the path to the Trac environment:

  $ bittend --verbose --log=/var/log/bittend /var/trac/myproject


Running the Build Slave
-----------------------

The build slave can be run on any machine that can connect to the machine
on which the build master is running. Just as with the build master script,
you should find the build slave script on your path after the installation.
The build slave script is called `bitten`.

To get a list of options for the build slave, execute it with the `--help`
option:

  $ bitten --help

To run the build slave against a slave installed on myproject.example.org,
you'd run:

  $ bitten myproject.example.org


More Information
----------------

For further documentation, please see the Bitten website at:

  <http://bitten.cmlenz.net/>