Mercurial > bitten > bitten-test

annotate doc/recipes.txt @ 451:57822fefd441

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix default for poll interval of slave.
author cmlenz
date Thu, 30 Aug 2007 08:07:22 +0000
parents d139ac1d216a
children dcde61c928af
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
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
39 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
40 repository.
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
41
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
42 .. code-block:: xml
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
43
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
44 <build xmlns:python="http://bitten.cmlenz.net/tools/python"
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
45 xmlns:svn="http://bitten.cmlenz.net/tools/svn">
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
46
445
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
47 <step id="build" description="Checkout source from repository">
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
48 <svn:checkout url="http://svn.example.org/repos/foo"
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
49 path="${path}" revision="${revision}" />
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
50 </step>
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
51
d139ac1d216a Add checkout command to example recipe.
cmlenz
parents: 412
diff changeset
52 <step id="checkout" description="Compile to byte code">
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
53 <python:distutils command="build"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
54 </step>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
55
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
56 <step id="test" description="Run unit tests">
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
57 <python:distutils command="unittest"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
58 <python:unittest file="build/test-results.xml"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
59 <python:trace summary="build/test-coverage.txt"
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
60 coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
61 </step>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
62
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
63 </build>
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
64
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
65 See `Build Recipe Commands`_ for a comprehensive reference of the commands
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
66 available by default.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
67
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
68 .. _`build recipe commands`: commands.html
Copyright (C) 2012-2017 Edgewall Software