Mercurial > bitten > bitten-test
comparison doc/recipes.txt @ 412:84b8cde2dfd4
Start with documentation.
| author | cmlenz |
|---|---|
| date | Tue, 07 Aug 2007 12:52:09 +0000 |
| parents | |
| children | d139ac1d216a |
comparison
equal
deleted
inserted
replaced
| 411:a169d2e96463 | 412:84b8cde2dfd4 |
|---|---|
| 1 .. -*- mode: rst; encoding: utf-8 -*- | |
| 2 | |
| 3 ============= | |
| 4 Build Recipes | |
| 5 ============= | |
| 6 | |
| 7 A build recipe tells a build slave how a project is to be built. It consists of | |
| 8 multiple build steps, each defining a command to execute, and where artifacts | |
| 9 can be found after that command has successfully completed. | |
| 10 | |
| 11 Build recipes are intended to supplement existing project build files (such as | |
| 12 Makefiles), not to replace them. In general, a recipe will be much simpler than | |
| 13 the build file itself, because it doesn't deal with all the details of the | |
| 14 build. It just automates the execution of the build and lets the build slave | |
| 15 locate any artifacts and metrics data generated in the course of the build. | |
| 16 | |
| 17 A recipe can and should split the build into multiple separate steps so that the | |
| 18 build slave can provide better status reporting to the build master while the | |
| 19 build is still in progress. This is important for builds that might take long to | |
| 20 execute. In addition, build steps help organize the build results for a more | |
| 21 structured presentation. | |
| 22 | |
| 23 .. contents:: Contents | |
| 24 :depth: 2 | |
| 25 .. sectnum:: | |
| 26 | |
| 27 | |
| 28 File Format | |
| 29 =========== | |
| 30 | |
| 31 Build recipes are stored internally in an XML-based format. Recipe documents | |
| 32 have a single ``<build>`` root element with one or more ``<step>`` child | |
| 33 elements. The steps are executed in the order they appear in the recipe. | |
| 34 | |
| 35 A ``<step>`` element will consist of any number of commands and reports. Most of | |
| 36 these elements are declared in XML namespaces, where the namespace URI defines | |
| 37 a collection of related commands. | |
| 38 | |
| 39 .. code-block:: xml | |
| 40 | |
| 41 <build xmlns:python="http://bitten.cmlenz.net/tools/python"> | |
| 42 | |
| 43 <step id="build" description="Compile to byte code"> | |
| 44 <python:distutils command="build"/> | |
| 45 </step> | |
| 46 | |
| 47 <step id="test" description="Run unit tests"> | |
| 48 <python:distutils command="unittest"/> | |
| 49 <python:unittest file="build/test-results.xml"/> | |
| 50 <python:trace summary="build/test-coverage.txt" | |
| 51 coverdir="build/coverage" include="trac*" exclude="*.tests.*"/> | |
| 52 </step> | |
| 53 | |
| 54 </build> | |
| 55 | |
| 56 See `Build Recipe Commands`_ for a comprehensive reference of the commands | |
| 57 available by default. | |
| 58 | |
| 59 .. _`build recipe commands`: commands.html |