Mercurial > bitten > bitten-test
diff doc/recipes.txt @ 412:84b8cde2dfd4
Start with documentation.
author | cmlenz |
---|---|
date | Tue, 07 Aug 2007 12:52:09 +0000 |
parents | |
children | d139ac1d216a |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/recipes.txt @@ -0,0 +1,59 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +============= +Build Recipes +============= + +A build recipe tells a build slave how a project is to be built. It consists of +multiple build steps, each defining a command to execute, and where artifacts +can be found after that command has successfully completed. + +Build recipes are intended to supplement existing project build files (such as +Makefiles), not to replace them. In general, a recipe will be much simpler than +the build file itself, because it doesn't deal with all the details of the +build. It just automates the execution of the build and lets the build slave +locate any artifacts and metrics data generated in the course of the build. + +A recipe can and should split the build into multiple separate steps so that the +build slave can provide better status reporting to the build master while the +build is still in progress. This is important for builds that might take long to +execute. In addition, build steps help organize the build results for a more +structured presentation. + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +File Format +=========== + +Build recipes are stored internally in an XML-based format. Recipe documents +have a single ``<build>`` root element with one or more ``<step>`` child +elements. The steps are executed in the order they appear in the recipe. + +A ``<step>`` element will consist of any number of commands and reports. Most of +these elements are declared in XML namespaces, where the namespace URI defines +a collection of related commands. + +.. code-block:: xml + + <build xmlns:python="http://bitten.cmlenz.net/tools/python"> + + <step id="build" description="Compile to byte code"> + <python:distutils command="build"/> + </step> + + <step id="test" description="Run unit tests"> + <python:distutils command="unittest"/> + <python:unittest file="build/test-results.xml"/> + <python:trace summary="build/test-coverage.txt" + coverdir="build/coverage" include="trac*" exclude="*.tests.*"/> + </step> + + </build> + +See `Build Recipe Commands`_ for a comprehensive reference of the commands +available by default. + +.. _`build recipe commands`: commands.html