Installation
1 Prerequisites
Bitten is written in Python, so make sure that you have Python installed. You'll need Python 2.4 or later for running build slave. The build master is a plugin for Trac 0.11, and should still work with Python 2.3. Also, make sure that setuptools, version 0.6a2 or later, is installed.
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 by default 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 (please note that Trac needs to be installed for the tests to run; see below):
$ python setup.py test
It is also possible to install only the build slave, installing only the parts of Bitten that are needed by clients to run builds:
$ python setup.py --without-master install
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.11 or later. Please refer to the Trac documentation for information on how it is installed.
2 Build Master Configuration
Once both Bitten and Trac 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 Bitten plugin needs to be explicitly enabled in the Trac configuration. This is done by adding it to the [components] section in /path/to/projenv/conf/trac.ini:
[components] bitten.* = enabled
The Trac web interface should now 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 [yourname] BUILD_ADMIN $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
Build slaves (see next section) will need permission to download build configurations and submit results. You can grant the permission using:
$ trac-admin /path/to/projenv permission add [slavegroup] BUILD_EXEC
Alternatively you may allow anyone to submit builds by giving anonymous users this permission.
You should now see an additional tab labeled "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 Bitten is installed, and you are logged in as a user with the required permissions, you should see additional administration pages inside the “Admin” area, under a group named “Builds”. These pages allow you to set options of the build master, and manage build configurations.
Add a new build configuration and fill out the form. Also, add at least one target platform after saving the configuration. Last but not least, you'll have to "activate" your new build configuration.
3 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. The installation of Bitten should have put a bitten-slave executable 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 get a list of options for the build slave, execute it with the --help option:
$ bitten-slave --help
To run the build slave against a Bitten-enabled Trac site installed at http://myproject.example.org/trac, you'd run:
$ bitten-slave http://myproject.example.org/trac/builds
See also: Documentation
