cmlenz@189: About Bitten cmlenz@189: ============ cmlenz@189: cmlenz@189: Bitten is a simple distributed continuous integration system that not only cmlenz@189: coordinates builds across multiple machines, but also collects software cmlenz@189: metrics generated by builds, to enable feedback and reporting about cmlenz@189: the progress of a software project. cmlenz@189: osimons@652: The Bitten software consists of two separate parts: osimons@652: * The build slave, which executes builds on behalf of a build master. cmlenz@189: * The web interface, which is implemented as an add-on to Trac cmlenz@189: (http://trac.edgewall.com/) and provides a build management interface cmlenz@189: as well as presentation of build results. cmlenz@189: osimons@652: The build master is a plugin for Trac 0.11, while the build slave can be osimons@652: installed without other dependencies than Python >= 2.4 and osimons@652: setuptools >= 0.6a2 in addition to any tools required by the build process osimons@652: itself. A build slave may be run on any machine that can connect to the server cmlenz@319: running the Bitten build master. cmlenz@189: cmlenz@189: cmlenz@189: Installation cmlenz@189: ------------ cmlenz@189: cmlenz@189: Bitten is written in Python, so make sure that you have Python installed. osimons@654: You'll need Python 2.4 or later for running build slave, while the Trac plugin osimons@654: (master) should still work using Python 2.3. Also, make sure that setuptools cmlenz@207: (http://peak.telecommunity.com/DevCenter/setuptools), version 0.6a2 or later, cmlenz@207: is installed. cmlenz@189: cmlenz@189: If that's taken care of, you just need to download and unpack the Bitten cmlenz@189: distribution, and execute the command: cmlenz@189: cmlenz@189: $ python setup.py install cmlenz@189: cmlenz@189: from the top of the directory where you unpacked (or checked out) the Bitten cmlenz@189: code. Note that you may need administrator/root privileges for this step, as cmlenz@319: it will by default attempt to install Bitten to the Python site-packages cmlenz@319: directory on your system. cmlenz@189: cmlenz@189: It's also a good idea to run the unit tests at this point, to make sure that cmlenz@189: the code works as expected on your platform: cmlenz@189: cmlenz@189: $ python setup.py test cmlenz@189: osimons@684: It is also possible to install only the build slave, installing only the osimons@684: parts of Bitten that are needed by clients to run builds: osimons@684: osimons@684: $ python setup.py --without-master install cmlenz@189: cmlenz@189: What's left to do now depends on whether you want to use the build master and cmlenz@189: web interface, or just the build slave. In the latter case, you're already cmlenz@189: done. You might need to install software that the build of your project cmlenz@189: requires, but the Bitten build slave itself doesn't require anything extra. cmlenz@189: osimons@651: For the build master and web interface, you'll need to install Trac 0.11 or cmlenz@330: later. Please refer to the Trac documentation for information on how it is cmlenz@330: installed. cmlenz@189: cmlenz@189: cmlenz@189: Build Master Configuration cmlenz@189: -------------------------- cmlenz@189: cmlenz@207: Once both Bitten and Trac are installed and working, you'll have to introduce cmlenz@207: Bitten to your Trac project environment. If you don't have a Trac project cmlenz@207: set up yet, you'll need to do so in order to use Bitten. cmlenz@189: cmlenz@319: If you already have a Trac project environment, the Bitten plugin needs to be cmlenz@319: explicitly enabled in the Trac configuration. This is done by adding it to the cmlenz@319: [components] section in /path/to/projenv/conf/trac.ini: cmlenz@319: cmlenz@319: [components] cmlenz@319: bitten.* = enabled cmlenz@319: cmlenz@319: The Trac web interface should now inform you with an error message that the cmlenz@319: environment needs to be upgraded. To do this, run: cmlenz@189: cmlenz@189: $ trac-admin /path/to/projenv upgrade cmlenz@189: cmlenz@189: This will create the database tables and directories that Bitten requires. cmlenz@189: You probably also want to grant permissions to someone (such as yourself) cmlenz@189: to manage build configurations, and allow anonymous users to view the cmlenz@189: status and results of builds: cmlenz@189: cmlenz@393: $ trac-admin /path/to/projenv permission add anonymous BUILD_EXEC cmlenz@189: $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW cmlenz@189: $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN cmlenz@189: cmlenz@319: You should now see an additional tab labeled "Build Status" in the Trac cmlenz@189: navigation bar. This link will take you to the list of build configurations, cmlenz@189: which at this point is of course empty. If you've set up permissions cmlenz@189: correctly as described previously, you should see a button for adding new cmlenz@189: build configurations. Click that button and fill out the form. Also, add cmlenz@189: at least one target platform after saving the configuration. Last but not cmlenz@190: least, you'll have to "activate" the build configuration. cmlenz@189: cmlenz@189: cmlenz@189: Running the Build Slave cmlenz@189: ----------------------- cmlenz@189: cmlenz@189: The build slave can be run on any machine that can connect to the machine cmlenz@393: on which the build master is running. The installation of Bitten should have put cmlenz@393: a `bitten-slave` executable on your path. If the script is not on your path, cmlenz@393: look for it in the `bin` or `scripts` subdirectory of your Python installation. cmlenz@189: cmlenz@189: To get a list of options for the build slave, execute it with the `--help` cmlenz@189: option: cmlenz@189: cmlenz@207: $ bitten-slave --help cmlenz@189: cmlenz@393: To run the build slave against a Bitten-enabled Trac site installed at cmlenz@393: http://myproject.example.org/trac, you'd run: cmlenz@189: cmlenz@393: $ bitten-slave http://myproject.example.org/trac/builds cmlenz@189: cmlenz@189: cmlenz@189: More Information cmlenz@189: ---------------- cmlenz@189: cmlenz@189: For further documentation, please see the Bitten website at: cmlenz@189: osimons@582: