Mercurial > bitten > bitten-test

annotate doc/recipes.txt @ 899:6ac02ad71cc4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update ChangeLog before 0.6 release.
author hodgestar
date Fri, 11 Mar 2011 11:10:41 +0000
parents 025b3e889321
children
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
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
24 File Format
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
25 ===========
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
26
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
27 Build recipes are stored internally in an XML-based format. Recipe documents
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
28 have a single ``<build>`` root element with one or more ``<step>`` child
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
29 elements. The steps are executed in the order they appear in the recipe.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
30
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
31 A ``<step>`` element will consist of any number of commands and reports. Most of
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
32 these elements are declared in XML namespaces, where the namespace URI defines
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
33 a collection of related commands.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
34
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
35
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
36 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
37 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
38 values are:
775
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
39
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
40 - ``fail``: failure of a step causes the build to terminate. (default)
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
41
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
42 - ``continue``: builds continue after step failures. Failing steps
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
43 contribute to the overall build status.
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
44
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
45 - ``ignore``: builds continue after step failures. Builds are marked
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
46 as successful even in the presence of failed steps with
025b3e889321 Doc fixes. Making docs compile without errors + some minor tweaks to output.
osimons
parents: 754
diff changeset
47 onerror='ignore'
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
48
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 ``<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
50 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
51
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
52 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
53 repository.
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
54
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
55 .. code-block:: xml
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
56
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
57 <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
58 xmlns:svn="http://bitten.edgewall.org/tools/svn">
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
59
456
dcde61c928af Add debug log message for enabling authentication.
cmlenz
parents: 445
diff changeset
60 <step id="checkout" description="Checkout source from repository">
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
61 <svn:checkout url="http://svn.example.org/repos/foo"
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
62 path="${path}" revision="${revision}" />
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
63 </step>
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
64
456
dcde61c928af Add debug log message for enabling authentication.
cmlenz
parents: 445
diff changeset
65 <step id="build" description="Compile to byte code">
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
66 <python:distutils command="build"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
67 </step>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
68
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
69 <step id="test" description="Run unit tests">
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
70 <python:distutils command="unittest"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
71 <python:unittest file="build/test-results.xml"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
72 <python:trace summary="build/test-coverage.txt"
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
73 coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
74 </step>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
75
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
76 </build>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
77
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
78 See `Build Recipe Commands`_ for a comprehensive reference of the commands
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
79 available by default.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
80
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
81 .. _`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
82
749
94a4be5a1f0f Somewhat improve paragraph introducing recipe variables.
hodgestar
parents: 706
diff changeset
83 Recipes may contain variables, for example ``${path}``, which are expanded
94a4be5a1f0f Somewhat improve paragraph introducing recipe variables.
hodgestar
parents: 706
diff changeset
84 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
85 but custom variables may be added (see `Slave Configuration`_ for further
94a4be5a1f0f Somewhat improve paragraph introducing recipe variables.
hodgestar
parents: 706
diff changeset
86 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
87
611
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
88 .. _`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
89
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 +-----------------+----------------------------------------------------------+
749
94a4be5a1f0f Somewhat improve paragraph introducing recipe variables.
hodgestar
parents: 706
diff changeset
91 | 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
92 +=================+==========================================================+
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 | ``${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
94 +-----------------+----------------------------------------------------------+
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 | ``${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
96 +-----------------+----------------------------------------------------------+
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 | ``${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
98 +-----------------+----------------------------------------------------------+
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 | ``${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
100 +-----------------+----------------------------------------------------------+
611
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
101 | ``${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
102 +-----------------+----------------------------------------------------------+
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
103 | ``${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
104 +-----------------+----------------------------------------------------------+
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
105 | ``${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
106 | | ``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
107 +-----------------+----------------------------------------------------------+
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
108
588
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
109 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
110 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
111
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 | Character | Quoted |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
114 +===========+============+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
115 | ``"`` | ``&quot;`` |
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 | ``<`` | ``&lt;`` |
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 | ``>`` | ``&gt;`` |
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 | ``&`` | ``&amp;`` |
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 | ``'`` | ``&apos;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
124 +-----------+------------+
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
125
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 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
127 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
128 (``&quot;``) 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
129 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
130 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
131 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
132
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 .. 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
134
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 <sh:exec file="echo" args="o\\ne &quot;4 2&quot; \&quot;hi\ there\&quot;"/>
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
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 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
138
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 **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
140 This may affect quoting of arguments.
Copyright (C) 2012-2017 Edgewall Software