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 documents 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. Most of these elements are declared in XML namespaces, where the namespace URI defines a collection of related commands.

The <build> element can optionally have an onerror attribute that dictates how a build should proceed after the failure of a step. Allowable values are:

• fail: failure of a step causes the build to terminate. (default)
• continue: builds continue after step failures. Failing steps contribute to the overall build status.
• ignore: builds continue after step failures. Builds are marked as successful even in the presence of failed steps with onerror='ignore'

<step> elements can override the <build> onerror attribute with their own onerror attributes.

Commonly, the first step of any build recipe will perform the checkout from the repository.

<build xmlns:python="http://bitten.edgewall.org/tools/python"
       xmlns:svn="http://bitten.edgewall.org/tools/svn">
  <step id="checkout" description="Checkout source from repository">
    <svn:checkout url="http://svn.example.org/repos/foo"
        path="${path}" revision="${revision}" />
  </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>

See Build Recipe Commands for a comprehensive reference of the commands available by default.

Recipes may contain variables, for example ${path}, which are expanded before the recipe is executed. A small set of variables is pre-defined but custom variables may be added (see Slave Configuration for further instructions). The pre-defined recipe variables are:

Variable name	Expanded value
${path}	Repository path from the build configuration
${config}	The build configuration name
${build}	The index of this build request
${revision}	The repository revision being tested
${reponame}	Then name of the repository as derived from path
${repopath}	The path as seen from inside the repository
${platform}	The name of the target platform being built
${name}	The name of the build slave
${basedir}	The absolute path of the build location, joining work-dir (absolute) with build-dir (relative)

As the recipe needs to be valid XML, any reserved characters in attributes must be quoted using regular XML entities:

Character	Quoted
"	"
<	&lt;
>	&gt;
&	&amp;
'	&apos;

If needed, most commands use regular shell rules to split parts of the input - typically like args input for sh:exec command. Double-quotes (&quot;) can be used to mark the start and end if any sub-parts contain whitespace, alternatively '\' can be used to escape whitespace or any other character that carries meaning as part of input - including double-quotes and backslash itself:

<sh:exec file="echo" args="o\\ne &quot;4 2&quot; \&quot;hi\ there\&quot;"/>

This will pass 3 arguments: o\ne + 4 2 + "hi there".

Note: On Windows, batch scripts and built-ins will execute through a shell. This may affect quoting of arguments.

---

See also: Documentation