Mercurial > bitten > bitten-test

annotate doc/recipes.txt @ 617:327dca35a74f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensions to allow running all appropriate unittests from `Bitten-Slave` distribution: * Include all the runnable test packages * Include `bitten.util.loc` - all `bitten.util` submodules should be included as `bitten.build` steps depend on them * Specify `test_suite` as `bitten.slave_tests` * Add ` unittest` distutils command * Adjust `MANIFEST-SLAVE.in` to include all neccessary modules (including `setup.py` as `setup-slave.py` now depends on it
author dfraser
date Wed, 05 Aug 2009 09:43:15 +0000
parents 294641e84e89
children 7a8ddf54f012
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
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
611
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
78 .. _`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
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 +-----------------+----------------------------------------------------------+
611
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
91 | ``${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
92 +-----------------+----------------------------------------------------------+
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
93 | ``${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
94 +-----------------+----------------------------------------------------------+
294641e84e89 0.6dev: Adding `${name}` and `${basedir}` (#325) for recipe substitution. Updated docs + new test.
osimons
parents: 599
diff changeset
95 | ``${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
96 | | ``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
97 +-----------------+----------------------------------------------------------+
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
98
588
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
99 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
100 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
101
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 | Character | Quoted |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
104 +===========+============+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
105 | ``"`` | ``&quot;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
106 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
107 | ``<`` | ``&lt;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
108 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
109 | ``>`` | ``&gt;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
110 +-----------+------------+
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
111 | ``&`` | ``&amp;`` |
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 | ``'`` | ``&apos;`` |
ba53929c8652 0.6dev: Added some documentation about XML quoting in recipes (attributes), closing #360.
osimons
parents: 456
diff changeset
114 +-----------+------------+
Copyright (C) 2012-2017 Edgewall Software