412
|
1 .. -*- mode: rst; encoding: utf-8 -*-
|
|
2
|
|
3 =============
|
|
4 Build Recipes
|
|
5 =============
|
|
6
|
|
7 A build recipe tells a build slave how a project is to be built. It consists of
|
|
8 multiple build steps, each defining a command to execute, and where artifacts
|
|
9 can be found after that command has successfully completed.
|
|
10
|
|
11 Build recipes are intended to supplement existing project build files (such as
|
|
12 Makefiles), not to replace them. In general, a recipe will be much simpler than
|
|
13 the build file itself, because it doesn't deal with all the details of the
|
|
14 build. It just automates the execution of the build and lets the build slave
|
|
15 locate any artifacts and metrics data generated in the course of the build.
|
|
16
|
|
17 A recipe can and should split the build into multiple separate steps so that the
|
|
18 build slave can provide better status reporting to the build master while the
|
|
19 build is still in progress. This is important for builds that might take long to
|
|
20 execute. In addition, build steps help organize the build results for a more
|
|
21 structured presentation.
|
|
22
|
|
23 .. contents:: Contents
|
|
24 :depth: 2
|
|
25 .. sectnum::
|
|
26
|
|
27
|
|
28 File Format
|
|
29 ===========
|
|
30
|
|
31 Build recipes are stored internally in an XML-based format. Recipe documents
|
|
32 have a single ``<build>`` root element with one or more ``<step>`` child
|
|
33 elements. The steps are executed in the order they appear in the recipe.
|
|
34
|
|
35 A ``<step>`` element will consist of any number of commands and reports. Most of
|
|
36 these elements are declared in XML namespaces, where the namespace URI defines
|
|
37 a collection of related commands.
|
|
38
|
|
39 .. code-block:: xml
|
|
40
|
|
41 <build xmlns:python="http://bitten.cmlenz.net/tools/python">
|
|
42
|
|
43 <step id="build" description="Compile to byte code">
|
|
44 <python:distutils command="build"/>
|
|
45 </step>
|
|
46
|
|
47 <step id="test" description="Run unit tests">
|
|
48 <python:distutils command="unittest"/>
|
|
49 <python:unittest file="build/test-results.xml"/>
|
|
50 <python:trace summary="build/test-coverage.txt"
|
|
51 coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
|
|
52 </step>
|
|
53
|
|
54 </build>
|
|
55
|
|
56 See `Build Recipe Commands`_ for a comprehensive reference of the commands
|
|
57 available by default.
|
|
58
|
|
59 .. _`build recipe commands`: commands.html
|