Mercurial > bitten > bitten-test

annotate doc/recipes.txt @ 412:84b8cde2dfd4

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