cmlenz@412: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@412: 
cmlenz@412: ============
cmlenz@412: Installation
cmlenz@412: ============
cmlenz@412: 
cmlenz@412: .. contents:: Contents
cmlenz@412:    :depth: 2
cmlenz@412: .. sectnum::
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Prerequisites
cmlenz@412: =============
cmlenz@412: 
cmlenz@412: Bitten is written in Python, so make sure that you have Python installed.
osimons@657: You'll need Python 2.4 or later for running build slave. The build master is
osimons@658: a plugin for Trac_ 0.11, and should still work with Python 2.3. Also, make
osimons@657: sure that setuptools_, version 0.6a2 or later, is installed.
cmlenz@412: 
osimons@658: .. _trac:       http://trac.edgewall.org
cmlenz@412: .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
cmlenz@412: 
cmlenz@412: If that's taken care of, you just need to download and unpack the Bitten
cmlenz@412: distribution, and execute the command::
cmlenz@412: 
cmlenz@412:   $ python setup.py install
cmlenz@412: 
cmlenz@412: from the top of the directory where you unpacked (or checked out) the Bitten
cmlenz@412: code. Note that you may need administrator/root privileges for this step, as
cmlenz@412: it will by default attempt to install Bitten to the Python site-packages
cmlenz@412: directory on your system.
cmlenz@412: 
cmlenz@412: It's also a good idea to run the unit tests at this point, to make sure that
dfraser@522: the code works as expected on your platform (please note that Trac_ needs to
dfraser@522: be installed for the tests to run; see below)::
cmlenz@412: 
cmlenz@412:   $ python setup.py test
cmlenz@412: 
osimons@598: It is also possible to install only the build slave, installing only the
osimons@598: parts of Bitten that are needed by clients to run builds::
osimons@598: 
osimons@682:   $ python setup.py --without-master install
cmlenz@412: 
cmlenz@412: What's left to do now depends on whether you want to use the build master and
cmlenz@412: web interface, or just the build slave. In the latter case, you're already
cmlenz@412: done. You might need to install software that the build of your project
cmlenz@412: requires, but the Bitten build slave itself doesn't require anything extra.
cmlenz@412: 
dfraser@523: For the build master and web interface, you'll need to install Trac_ 0.11 or
dfraser@555: later. Please refer to the Trac documentation for information on how it is installed.
cmlenz@436: 
cmlenz@412: 
cmlenz@412: Build Master Configuration
cmlenz@412: ==========================
cmlenz@412: 
cmlenz@412: Once both Bitten and Trac are installed and working, you'll have to introduce
cmlenz@412: Bitten to your Trac project environment. If you don't have a  Trac project
cmlenz@412: set up yet, you'll need to do so in order to use Bitten.
cmlenz@412: 
cmlenz@412: If you already have a Trac project environment, the Bitten plugin needs to be
cmlenz@412: explicitly enabled in the Trac configuration. This is done by adding it to the
cmlenz@436: ``[components]`` section in ``/path/to/projenv/conf/trac.ini``:
cmlenz@412: 
cmlenz@412: .. code-block:: ini
cmlenz@412: 
cmlenz@412:   [components]
cmlenz@412:   bitten.* = enabled
cmlenz@412: 
cmlenz@412: The Trac web interface should now inform you with an error message that the
cmlenz@412: environment needs to be upgraded. To do this, run::
cmlenz@412: 
cmlenz@412:   $ trac-admin /path/to/projenv upgrade
cmlenz@412: 
cmlenz@412: This will create the database tables and directories that Bitten requires.
cmlenz@412: You probably also want to grant permissions to someone (such as yourself)
cmlenz@412: to manage build configurations, and allow anonymous users to view the
cmlenz@412: status and results of builds::
cmlenz@412: 
hodgestar@739:   $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN
cmlenz@412:   $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
hodgestar@739: 
hodgestar@739: Build slaves (see next section) will need permission to download build
hodgestar@739: configurations and submit results. You can grant the permission using::
hodgestar@739: 
hodgestar@739:   $ trac-admin /path/to/projenv permission add [slavegroup] BUILD_EXEC
hodgestar@739: 
hodgestar@739: Alternatively you may allow anyone to submit builds by giving anonymous
hodgestar@739: users this permission.
cmlenz@412: 
cmlenz@412: You should now see an additional tab labeled "Build Status" in the Trac
cmlenz@412: navigation bar. This link will take you to the list of build configurations,
cmlenz@436: which at this point is of course empty.
cmlenz@436: 
dfraser@555: If Bitten is installed, and you are logged in as a user with the required
dfraser@555: permissions, you should see additional administration pages inside the “Admin”
dfraser@555: area, under a group named “Builds”. These pages allow you to set options of the
dfraser@555: build master, and manage build configurations.
cmlenz@436: 
cmlenz@436: Add a new build configuration and fill out the form. Also, add at least one
cmlenz@436: target platform after saving the configuration. Last but not least, you'll have
cmlenz@436: to "activate" your new build configuration.
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Running the Build Slave
cmlenz@412: =======================
cmlenz@412: 
cmlenz@412: The build slave can be run on any machine that can connect to the machine
cmlenz@412: on which the build master is running. The installation of Bitten should have put
cmlenz@412: a `bitten-slave` executable on your path. If the script is not on your path,
cmlenz@412: look for it in the `bin` or `scripts` subdirectory of your Python installation.
cmlenz@412: 
cmlenz@412: To get a list of options for the build slave, execute it with the `--help`
cmlenz@412: option::
cmlenz@412: 
cmlenz@412:   $ bitten-slave --help
cmlenz@412: 
cmlenz@412: To run the build slave against a Bitten-enabled Trac site installed at 
cmlenz@412: http://myproject.example.org/trac, you'd run::
cmlenz@412: 
cmlenz@412:   $ bitten-slave http://myproject.example.org/trac/builds