= Bitten Build Recipes =

{{{
#!div class=important
The content on this page is maintained as part of default documentation - see [wiki:Documentation/recipes.html]
}}}

  ''Note: the recipe format has changed since [milestone:0.4]. You can find documentation about the previous format by looking at version 6 of this page (see the “page history” link above).''

A ''build recipe'' tells 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 stored internally in an XML-based format. Recipe files have a single `<build>` 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 URI defines a collection of commands:

{{{
#!xml
<build xmlns:python="http://bitten.cmlenz.net/tools/python"
       xmlns:c="http://bitten.cmlenz.net/tools/c"
  >
  <step id="make" description="Make a C utility">
    <c:make target="compile" file="build/Makefile" />
  </step>

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

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

</build>
}}}
Note, each command must have suitable xmlns(eg. xmlns:c), otherwise it will fail.

Additional note: steps can also have '''onerror''' attribute with possible values of "fail" (the default), "continue" (you want the next step to run anyway -- tests followed by other tests are a good example), and 'ignore'.

== Recipe Command Binding ==

Recipe commands and report generators are mapped to Python functions using [http://peak.telecommunity.com/DevCenter/PkgResources#entry-points entry points]. Bitten itself comes with a number of entry points that provide recipe commands, but third-party packages can provide additional commands by declaring their own `bitten.recipe_commands` entry points.

The values of attributes on recipe command elements are passed to the function as keyword arguments. Special care must be taken with names that are either not valid Python identifiers, or that conflict with Python keywords or built-in functions. Dashes in names are replaced with underscores, and names that conflict with keywords or built-in functions get an underscore appended.

So, for example:
{{{
#!xml
  <foo:bar file="tools/tabcheck.py" ignore-errors="yes"/>
}}}

gets translated into:
{{{
#!python
  bar(ctxt, file_='tools/tabcheck.py', ignore_errors='yes')
}}}

== Property Interpolation ==

As described [SlaveConfiguration#PropertyInterpolationinBuildRecipes here], properties from a slave's configuration file can be interpolated into recipes.  In addition to those properties, Bitten pre-defines the following:

||'''Constant'''||'''Value'''||
||{{{${path}}}}||The repository path from the BuildConfiguration||
||{{{${config}}}}||The BuildConfiguration name||
||{{{${build}}}}||The index of this build request||
||{{{${revision}}}}||The repository revision being tested||


== See Also ==
 * Currently available [wiki:Documentation/commands.html RecipeCommands]
 * Instructions for how to use BoostTest with bitten.
 * [wiki:CommonXslts Common XSLTs]