= Bitten Build Recipes =

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 URL is a pseudo-protocol that defines which Python module they are implemented in:

{{{
#!xml
<build description="My project"
    xmlns:python="bitten:bitten.build.pythontools">

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

  <step id="test" description="Run unit tests">
    <python: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>

</build>
}}}

== Recipe Command Binding ==

As noted above, recipe commands and report generators are mapped to Python modules using XML namespaces. The URI of recipe namespace that uses the ''bitten'' scheme is mapped to the corresponding module. Commands and report generators are then mapped to functions inside that module.

For example, the command `<python:distutils>` (where the namespace prefix `python` resolves to `bitten:bitten.build.pythontools`) is mapped to the function `distutils` in the `bitten.build.pythontools` module. The function is invoked with any provided attributes passed as keyword arguments.

So, the XML snippet:
{{{
  <python:distutils command="build"/>
}}}

gets tranlated into:
{{{
from bitten.build.pythontools import distutils
distutils(ctxt, command='build')
}}}

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:
{{{
  <python:exec file="tools/tabcheck.py"/>
}}}

gets tranlated into:
{{{
from bitten.build.pythontools import exec_
exec_(ctxt, file_='tools/tabcheck.py')
}}}