Mercurial > bitten > bitten-test

annotate doc/recipes.txt @ 753:d9f06a314db5 0.6.x

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge [830] from trunk.
author wbell
date Sat, 24 Apr 2010 13:34:45 +0000
parents 132f6e23ffaf
children 545be0c8f405
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
611
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
39 A ``<step>`` element can additionally have an ``onerror`` attribute with
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
40 value of ``fail`` (terminate after step, default behaviour) or ``ignore``
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
41 (fail, but run next step).
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
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
684
a9157ac17ff9 0.6dev: Merging [758:759] from trunk.
osimons
parents: 671
diff changeset
48 <build xmlns:python="http://bitten.edgewall.org/tools/python"
a9157ac17ff9 0.6dev: Merging [758:759] from trunk.
osimons
parents: 671
diff changeset
49 xmlns:svn="http://bitten.edgewall.org/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
750
132f6e23ffaf Merge [827] from trunk.
hodgestar
parents: 707
diff changeset
74 Recipes may contain variables, for example ``${path}``, which are expanded
132f6e23ffaf Merge [827] from trunk.
hodgestar
parents: 707
diff changeset
75 before the recipe is executed. A small set of variables is pre-defined
132f6e23ffaf Merge [827] from trunk.
hodgestar
parents: 707
diff changeset
76 but custom variables may be added (see `Slave Configuration`_ for further
132f6e23ffaf Merge [827] from trunk.
hodgestar
parents: 707
diff changeset
77 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
78
611
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
79 .. _`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
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 +-----------------+----------------------------------------------------------+
750
132f6e23ffaf Merge [827] from trunk.
hodgestar
parents: 707
diff changeset
82 | 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
83 +=================+==========================================================+
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 | ``${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
85 +-----------------+----------------------------------------------------------+
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 | ``${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
87 +-----------------+----------------------------------------------------------+
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 | ``${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
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 | ``${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
91 +-----------------+----------------------------------------------------------+
611
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
92 | ``${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
93 +-----------------+----------------------------------------------------------+
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
94 | ``${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
95 +-----------------+----------------------------------------------------------+
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
96 | ``${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
97 | | ``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
98 +-----------------+----------------------------------------------------------+
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
99
588
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
100 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
101 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
102
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 | Character | Quoted |
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 | ``"`` | ``&quot;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
107 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
108 | ``<`` | ``&lt;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
109 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
110 | ``>`` | ``&gt;`` |
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 | ``&`` | ``&amp;`` |
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 | ``'`` | ``&apos;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
115 +-----------+------------+
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
116
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
117 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
118 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
119 (``&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
120 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
121 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
122 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
123
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
124 .. 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
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 <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
127
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 This will pass 3 arguments: ``o\ne`` + ``4 2`` + ``"hi there"``.
707
ac23fd566bd6 0.6dev: Merged [784] from trunk.
osimons
parents: 684
diff changeset
129
ac23fd566bd6 0.6dev: Merged [784] from trunk.
osimons
parents: 684
diff changeset
130 **Note:** On Windows, batch scripts and built-ins will execute through a shell.
ac23fd566bd6 0.6dev: Merged [784] from trunk.
osimons
parents: 684
diff changeset
131 This may affect quoting of arguments.
Copyright (C) 2012-2017 Edgewall Software