Bitten Build Recipes

A build recipe instructs a build slave how a project is to be built. It consists of multiple build steps, each defining a command to execute, and where artifacts can be found after that command has successfully completed.

Build recipes are intended to supplement existing project build files (such as Makefiles), not to replace them. In general, a recipe will be much simpler than the build file itself, because it doesn't deal with all the details of the build. It just automates the execution of the build and lets the build slave locate any artifacts and metrics data generated in the course of the build.

A recipe can and should split the build into multiple separate steps so that the build slave can provide better status reporting to the build master while the build is still in progress. This is important for builds that might take long to execute. In addition, build steps help organize the build results for a more structured presentation.

File Format

Build recipes are written in a custom XML-based format. Recipe files have a single <recipe> root element with one or more <step> child elements. The steps are executed in the order they appear in the recipe. A <step> element will consist of any number of commands and reports. These elements are declared in XML namespaces, where the namespace URL is a pseudo-protocol that defines which Python module they are implemented in:

<?xml version="1.0"?>
<recipe description="My project"
    xmlns:python="bitten:bitten.recipe.pythontools">

  <step id="build" description="Compile to byte code">
    <pthon:distutils command="build"/>
  </step>

  <step id="test" description="Run unit tests">
    <pthon:distutils command="unittest"/>
    <reports>
      <python:unittest file="build/test-results.xml"/>
      <python:trace summary="build/test-coverage.txt" 
          coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
    </reports>
  </step>

</recipe>