Mercurial > bitten > bitten-test

annotate doc/recipes.txt @ 599:b76e6accad72

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
author osimons
date Thu, 30 Jul 2009 09:47:48 +0000
parents ba53929c8652
children 294641e84e89
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
599
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
39 A ``<step>```element can additionally have a ``onerror`` attribute with possible
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
40 values of ``fail`` (terminate after step, default behaviour), or ``continue``
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
41 (fail, but run next step), or ``ignore`` (errors are unimportant, continue).
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
42
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
43 Commonly, the first step of any build recipe will perform the checkout from the
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
44 repository.
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
45
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
46 .. code-block:: xml
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
47
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
48 <build xmlns:python="http://bitten.cmlenz.net/tools/python"
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
49 xmlns:svn="http://bitten.cmlenz.net/tools/svn">
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
50
456
dcde61c928af Add debug log message for enabling authentication.
cmlenz
parents: 445
diff changeset
51 <step id="checkout" description="Checkout source from repository">
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
52 <svn:checkout url="http://svn.example.org/repos/foo"
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
53 path="${path}" revision="${revision}" />
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
54 </step>
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
55
456
dcde61c928af Add debug log message for enabling authentication.
cmlenz
parents: 445
diff changeset
56 <step id="build" description="Compile to byte code">
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
57 <python:distutils command="build"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
58 </step>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
59
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
60 <step id="test" description="Run unit tests">
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
61 <python:distutils command="unittest"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
62 <python:unittest file="build/test-results.xml"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
63 <python:trace summary="build/test-coverage.txt"
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
64 coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
65 </step>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
66
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
67 </build>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
68
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
69 See `Build Recipe Commands`_ for a comprehensive reference of the commands
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
70 available by default.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
71
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
72 .. _`build recipe commands`: commands.html
588
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
73
599
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
74 Recipes supports variables that can be interpolated into recipes, and using
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
75 `Slave Configuration`_ further custom properties can be used. Bitten supports
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
76 these pre-defined properties:
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
77
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
78 .. _`slave configuration`: slaveconfig.html
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
79
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
80 +-----------------+----------------------------------------------------------+
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
81 | Constant | Value |
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
82 +=================+==========================================================+
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
83 | ``${path}`` | Repository path from the build configuration |
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
84 +-----------------+----------------------------------------------------------+
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
85 | ``${config}`` | The build configuration name |
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
86 +-----------------+----------------------------------------------------------+
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
87 | ``${build}`` | The index of this build request |
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
88 +-----------------+----------------------------------------------------------+
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
89 | ``${revision}`` | The repository revision being tested |
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
90 +-----------------+----------------------------------------------------------+
b76e6accad72 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
osimons
parents: 588
diff changeset
91
588
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
92 As the recipe needs to be valid XML, any reserved characters in attributes must
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
93 be quoted using regular XML entities:
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
94
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
95 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
96 | Character | Quoted |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
97 +===========+============+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
98 | ``"`` | ``&quot;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
99 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
100 | ``<`` | ``&lt;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
101 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
102 | ``>`` | ``&gt;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
103 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
104 | ``&`` | ``&amp;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
105 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
106 | ``'`` | ``&apos;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
107 +-----------+------------+
Copyright (C) 2012-2017 Edgewall Software