bitten/bitten-test: doc/recipes.txt annotate

annotate doc/recipes.txt @ 891:60d0807334ec

Set 'Content-Length' header on keep-alive requests. Fixes #667. Thanks eblot.

author	osimons
date	Sat, 05 Mar 2011 02:15:03 +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 \| ``"`` \| ``"`` \|
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 +-----------+------------+
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 (``"``) 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 "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	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.

Mercurial > bitten > bitten-test

annotate doc/recipes.txt @ 891:60d0807334ec