cmlenz@412: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@412: 
cmlenz@412: =============
cmlenz@412: Build Recipes
cmlenz@412: =============
cmlenz@412: 
cmlenz@412: A build recipe tells a build slave how a project is to be built. It consists of
cmlenz@412: multiple build steps, each defining a command to execute, and where artifacts
cmlenz@412: can be found after that command has successfully completed.
cmlenz@412: 
cmlenz@412: Build recipes are intended to supplement existing project build files (such as
cmlenz@412: Makefiles), not to replace them. In general, a recipe will be much simpler than
cmlenz@412: the build file itself, because it doesn't deal with all the details of the
cmlenz@412: build. It just automates the execution of the build and lets the build slave
cmlenz@412: locate any artifacts and metrics data generated in the course of the build.
cmlenz@412: 
cmlenz@412: A recipe can and should split the build into multiple separate steps so that the
cmlenz@412: build slave can provide better status reporting to the build master while the
cmlenz@412: build is still in progress. This is important for builds that might take long to
cmlenz@412: execute. In addition, build steps help organize the build results for a more
cmlenz@412: structured presentation.
cmlenz@412: 
cmlenz@412: .. contents:: Contents
cmlenz@412:    :depth: 2
cmlenz@412: .. sectnum::
cmlenz@412: 
cmlenz@412: 
cmlenz@412: File Format
cmlenz@412: ===========
cmlenz@412: 
cmlenz@412: Build recipes are stored internally in an XML-based format. Recipe documents
cmlenz@412: have a single ``<build>`` root element with one or more ``<step>`` child
cmlenz@412: elements. The steps are executed in the order they appear in the recipe.
cmlenz@412: 
cmlenz@412: A ``<step>`` element will consist of any number of commands and reports. Most of
cmlenz@412: these elements are declared in XML namespaces, where the namespace URI defines
cmlenz@412: a collection of related commands.
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <build xmlns:python="http://bitten.cmlenz.net/tools/python">
cmlenz@412:   
cmlenz@412:     <step id="build" description="Compile to byte code">
cmlenz@412:       <python:distutils command="build"/>
cmlenz@412:     </step>
cmlenz@412:   
cmlenz@412:     <step id="test" description="Run unit tests">
cmlenz@412:       <python:distutils command="unittest"/>
cmlenz@412:       <python:unittest file="build/test-results.xml"/>
cmlenz@412:       <python:trace summary="build/test-coverage.txt" 
cmlenz@412:           coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
cmlenz@412:     </step>
cmlenz@412:   
cmlenz@412:   </build>
cmlenz@412: 
cmlenz@412: See `Build Recipe Commands`_ for a comprehensive reference of the commands
cmlenz@412: available by default.
cmlenz@412: 
cmlenz@412: .. _`build recipe commands`: commands.html