Mercurial > bitten > bitten-test
annotate doc/recipes.txt @ 754:545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
Added a new ''continue'' onerror specification-- it's similar to ''ignore''
except the results of ''continue'' steps are counted in the overall build
status (in ''ignore'' they're ignored.)
You'll need to upgrade both your master and slaves if you wish to use
the ''<build>'' element override or the new ''continue'' value.
Will update http://bitten.edgewall.org/wiki/Documentation/recipes.html .
Thanks to jerith for comments.
Closes #409.
Refs #210.
author | wbell |
---|---|
date | Sat, 24 Apr 2010 13:37:26 +0000 |
parents | 94a4be5a1f0f |
children | 025b3e889321 |
rev | line source |
---|---|
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 | |
754
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
39 |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
40 The ``<build>`` element can optionally have an ``onerror`` attribute that |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
41 dictates how a build should proceed after the failure of a step. Allowable |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
42 values are: |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
43 ``fail``: failure of a step causes the build to terminate. (default) |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
44 ``continue``: builds continue after step failures. Failing steps |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
45 contribute to the overall build status. |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
46 ``ignore``: builds continue after step failures. Builds are marked |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
47 as successful even in the presence of failed steps with |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
48 onerror='ignore' |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
49 |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
50 ``<step>`` elements can override the ``<build>`` ``onerror`` attribute with |
545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
wbell
parents:
749
diff
changeset
|
51 their own ``onerror`` attributes. |
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
|
52 |
445 | 53 Commonly, the first step of any build recipe will perform the checkout from the |
54 repository. | |
55 | |
412 | 56 .. code-block:: xml |
57 | |
683
0c4fec90c8e2
0.6dev: Update all tools and docs to use the new `http://bitten.edgewall.org/tools/` namespace as default. Old namespace will still work, but a notice appears when editing config if deprecated namespace is in use. Both will work for now, though.
osimons
parents:
671
diff
changeset
|
58 <build xmlns:python="http://bitten.edgewall.org/tools/python" |
0c4fec90c8e2
0.6dev: Update all tools and docs to use the new `http://bitten.edgewall.org/tools/` namespace as default. Old namespace will still work, but a notice appears when editing config if deprecated namespace is in use. Both will work for now, though.
osimons
parents:
671
diff
changeset
|
59 xmlns:svn="http://bitten.edgewall.org/tools/svn"> |
412 | 60 |
456 | 61 <step id="checkout" description="Checkout source from repository"> |
445 | 62 <svn:checkout url="http://svn.example.org/repos/foo" |
63 path="${path}" revision="${revision}" /> | |
64 </step> | |
65 | |
456 | 66 <step id="build" description="Compile to byte code"> |
412 | 67 <python:distutils command="build"/> |
68 </step> | |
69 | |
70 <step id="test" description="Run unit tests"> | |
71 <python:distutils command="unittest"/> | |
72 <python:unittest file="build/test-results.xml"/> | |
73 <python:trace summary="build/test-coverage.txt" | |
74 coverdir="build/coverage" include="trac*" exclude="*.tests.*"/> | |
75 </step> | |
76 | |
77 </build> | |
78 | |
79 See `Build Recipe Commands`_ for a comprehensive reference of the commands | |
80 available by default. | |
81 | |
82 .. _`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
|
83 |
749
94a4be5a1f0f
Somewhat improve paragraph introducing recipe variables.
hodgestar
parents:
706
diff
changeset
|
84 Recipes may contain variables, for example ``${path}``, which are expanded |
94a4be5a1f0f
Somewhat improve paragraph introducing recipe variables.
hodgestar
parents:
706
diff
changeset
|
85 before the recipe is executed. A small set of variables is pre-defined |
94a4be5a1f0f
Somewhat improve paragraph introducing recipe variables.
hodgestar
parents:
706
diff
changeset
|
86 but custom variables may be added (see `Slave Configuration`_ for further |
94a4be5a1f0f
Somewhat improve paragraph introducing recipe variables.
hodgestar
parents:
706
diff
changeset
|
87 instructions). The pre-defined recipe variables are: |
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
|
88 |
611
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
89 .. _`slave configuration`: configure.html |
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
|
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 +-----------------+----------------------------------------------------------+ |
749
94a4be5a1f0f
Somewhat improve paragraph introducing recipe variables.
hodgestar
parents:
706
diff
changeset
|
92 | Variable name | Expanded value | |
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
|
93 +=================+==========================================================+ |
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
|
94 | ``${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
|
95 +-----------------+----------------------------------------------------------+ |
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
|
96 | ``${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
|
97 +-----------------+----------------------------------------------------------+ |
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
|
98 | ``${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
|
99 +-----------------+----------------------------------------------------------+ |
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
|
100 | ``${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
|
101 +-----------------+----------------------------------------------------------+ |
611
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
102 | ``${platform}`` | The name of the target platform being built | |
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
103 +-----------------+----------------------------------------------------------+ |
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
104 | ``${name}`` | The name of the build slave | |
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
105 +-----------------+----------------------------------------------------------+ |
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
106 | ``${basedir}`` | The absolute path of the build location, joining | |
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
107 | | ``work-dir`` (absolute) with ``build-dir`` (relative) | |
294641e84e89
0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents:
599
diff
changeset
|
108 +-----------------+----------------------------------------------------------+ |
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
|
109 |
588
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
110 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
|
111 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
|
112 |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
113 +-----------+------------+ |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
114 | Character | Quoted | |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
115 +===========+============+ |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
116 | ``"`` | ``"`` | |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
117 +-----------+------------+ |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
118 | ``<`` | ``<`` | |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
119 +-----------+------------+ |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
120 | ``>`` | ``>`` | |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
121 +-----------+------------+ |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
122 | ``&`` | ``&`` | |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
123 +-----------+------------+ |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
124 | ``'`` | ``'`` | |
ba53929c8652
0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents:
456
diff
changeset
|
125 +-----------+------------+ |
671
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
126 |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
127 If needed, most commands use regular shell rules to split parts of the input - |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
128 typically like ``args`` input for ``sh:exec`` command. Double-quotes |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
129 (``"``) can be used to mark the start and end if any sub-parts contain |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
130 whitespace, alternatively ``'\'`` can be used to escape whitespace or any other |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
131 character that carries meaning as part of input - including double-quotes and |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
132 backslash itself: |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
133 |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
134 .. code-block:: xml |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
135 |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
136 <sh:exec file="echo" args="o\\ne "4 2" \"hi\ there\""/> |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
137 |
7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
osimons
parents:
611
diff
changeset
|
138 This will pass 3 arguments: ``o\ne`` + ``4 2`` + ``"hi there"``. |
706
d2e965fc31d4
On Windows, make `cmd.exe` built-ins and scripts execute through the shell. Closes #449 + generally improves handling for `<sh:exec file="mycript.bat">` type commands on Windows.
osimons
parents:
683
diff
changeset
|
139 |
d2e965fc31d4
On Windows, make `cmd.exe` built-ins and scripts execute through the shell. Closes #449 + generally improves handling for `<sh:exec file="mycript.bat">` type commands on Windows.
osimons
parents:
683
diff
changeset
|
140 **Note:** On Windows, batch scripts and built-ins will execute through a shell. |
d2e965fc31d4
On Windows, make `cmd.exe` built-ins and scripts execute through the shell. Closes #449 + generally improves handling for `<sh:exec file="mycript.bat">` type commands on Windows.
osimons
parents:
683
diff
changeset
|
141 This may affect quoting of arguments. |