# HG changeset patch # User cmlenz # Date 1125529123 0 # Node ID 2f0b36b313cc77a869ba90a199ab966e719f65c6 # Parent 5a67232c0d69c492ce0d4810077807725d9e2140 Added [source:trunk/README.txt README.txt] to explain installation, configuration and usage of Bitten. Closes #36. diff --git a/README.txt b/README.txt new file mode 100644 --- /dev/null +++ b/README.txt @@ -0,0 +1,133 @@ +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: + +