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: 
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: 
wbell@754: 
wbell@754: The ``<build>`` element can optionally have an ``onerror`` attribute that
wbell@754: dictates how a build should proceed after the failure of a step. Allowable
wbell@754: values are:
osimons@775: 
osimons@775: - ``fail``: failure of a step causes the build to terminate. (default)
osimons@775: 
osimons@775: - ``continue``: builds continue after step failures. Failing steps
osimons@775:   contribute to the overall build status.
osimons@775: 
osimons@775: - ``ignore``: builds continue after step failures. Builds are marked
osimons@775:   as successful even in the presence of failed steps with
osimons@775:   onerror='ignore'
wbell@754: 
wbell@754: ``<step>`` elements can override the ``<build>`` ``onerror`` attribute with
wbell@754: their own ``onerror`` attributes.
osimons@599: 
cmlenz@445: Commonly, the first step of any build recipe will perform the checkout from the
cmlenz@445: repository.
cmlenz@445: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
osimons@683:   <build xmlns:python="http://bitten.edgewall.org/tools/python"
osimons@683:          xmlns:svn="http://bitten.edgewall.org/tools/svn">
cmlenz@412:   
cmlenz@456:     <step id="checkout" description="Checkout source from repository">
cmlenz@445:       <svn:checkout url="http://svn.example.org/repos/foo"
cmlenz@445:           path="${path}" revision="${revision}" />
cmlenz@445:     </step>
cmlenz@445:   
cmlenz@456:     <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
osimons@588: 
hodgestar@749: Recipes may contain variables, for example ``${path}``, which are expanded
hodgestar@749: before the recipe is executed. A small set of variables is pre-defined
hodgestar@749: but custom variables may be added (see `Slave Configuration`_ for further
hodgestar@749: instructions). The pre-defined recipe variables are:
osimons@599: 
osimons@611: .. _`slave configuration`: configure.html
osimons@599: 
osimons@599: +-----------------+----------------------------------------------------------+
hodgestar@749: | Variable name   | Expanded value                                           |
osimons@599: +=================+==========================================================+
osimons@599: | ``${path}``     | Repository path from the build configuration             |
osimons@599: +-----------------+----------------------------------------------------------+
osimons@599: | ``${config}``   | The build configuration name                             |
osimons@599: +-----------------+----------------------------------------------------------+
osimons@599: | ``${build}``    | The index of this build request                          |
osimons@599: +-----------------+----------------------------------------------------------+
osimons@599: | ``${revision}`` | The repository revision being tested                     |
osimons@599: +-----------------+----------------------------------------------------------+
osimons@611: | ``${platform}`` | The name of the target platform being built              |
osimons@611: +-----------------+----------------------------------------------------------+
osimons@611: | ``${name}``     | The name of the build slave                              |
osimons@611: +-----------------+----------------------------------------------------------+
osimons@611: | ``${basedir}``  | The absolute path of the build location, joining         |
osimons@611: |                 | ``work-dir`` (absolute) with ``build-dir`` (relative)    |
osimons@611: +-----------------+----------------------------------------------------------+
osimons@599: 
osimons@588: As the recipe needs to be valid XML, any reserved characters in attributes must
osimons@588: be quoted using regular XML entities:
osimons@588: 
osimons@588: +-----------+------------+
osimons@588: | Character | Quoted     |
osimons@588: +===========+============+
osimons@588: | ``"``     | ``&quot;`` |
osimons@588: +-----------+------------+
osimons@588: | ``<``     | ``&lt;``   |
osimons@588: +-----------+------------+  
osimons@588: | ``>``     | ``&gt;``   |
osimons@588: +-----------+------------+
osimons@588: | ``&``     | ``&amp;``  |
osimons@588: +-----------+------------+
osimons@588: | ``'``     | ``&apos;`` |
osimons@588: +-----------+------------+
osimons@671: 
osimons@671: If needed, most commands use regular shell rules to split parts of the input -
osimons@671: typically like ``args`` input for ``sh:exec`` command. Double-quotes
osimons@671: (``&quot;``) can be used to mark the start and end if any sub-parts contain
osimons@671: whitespace, alternatively ``'\'`` can be used to escape whitespace or any other
osimons@671: character that carries meaning as part of input - including double-quotes and
osimons@671: backslash itself:
osimons@671: 
osimons@671: .. code-block:: xml
osimons@671: 
osimons@671:   <sh:exec file="echo" args="o\\ne &quot;4 2&quot; \&quot;hi\ there\&quot;"/>
osimons@671: 
osimons@671: This will pass 3 arguments: ``o\ne`` + ``4 2`` + ``"hi there"``.
osimons@706: 
osimons@706: **Note:** On Windows, batch scripts and built-ins will execute through a shell.
osimons@706: This may affect quoting of arguments.