Build Recipe Commands

Build recipes are represented by XML documents. This page describes what commands are generally available in recipes, and any runtime configuration supported by these commands. Please note, though, that third-party packages can add additional commands, which would then be documented by that third party.

Contents

1   Generic Commands

These are commands that are used without a namespace prefix.

1.1   <report>

Parse an XML file and send it to the master as a report with a given category. Use this command in conjunction with the <sh:pipe> or <x:transform> commands to send custom reports to the build master.

1.1.1   Parameters

Name Description
category Category of the report (for example "test" or "coverage").
file Path to the XML file containing the report data, relative to the project directory.

Both parameters must be specified.

See also Report Formats.

1.2   <attach>

Attach a file to the build or configuration as regular attachment. An already existing attachment on the same resource with same base filename will be replaced.

Note: Unless consistently building latest only, overwriting files on config level may lead to unexpected results.

1.2.1   Parameters

Name Description
file Path to the file to attach, relative to the project directory.
resource The resource to attach the file to. Either 'build' (default) or 'config'. Optional.
description Attachment description. Optional.

2   Shell Tools

A bundle of generic tools that are not specific to any programming language or tool-chain.

Namespace:http://bitten.edgewall.org/tools/sh
Common prefix:sh

2.1   <sh:exec>

Executes a program or script.

2.1.1   Parameters

Name Description
executable The name of the executable program.
file Path to the script to execute, relative to the project directory
output Path to the output file
args Any arguments to pass to the executable or script
dir Directory to change to before executing the command
timeout Limits the runtime of this command to the specified number of seconds, after which it will be terminated.

Either executable or file must be specified.

2.1.2   Examples

TODO

2.2   <sh:pipe>

Pipes the content of a file through a program or script.

2.2.1   Parameters

Name Description
executable The name of the executable program.
file Path to the script to execute, relative to the project directory
input Path to the input file
output Path to the output file
args Any arguments to pass to the executable or script
dir Directory to change to before executing the command

Either executable or file must be specified.

2.2.2   Examples

TODO

3   C/Unix Tools

These commands provide support for tools commonly used for development of C/C++ applications on Unix platforms, such as make.

Namespace:http://bitten.edgewall.org/tools/c
Common prefix:c

3.1   <c:autoreconf>

Executes ths autotool autoreconf.

3.1.1   Parameters

Name Description
force Consider all files obsolete
install Copy missing auxiliary files
symlink Install symbolic links instead of copies
warnings Report the warnings related to category (which can actually be a comma separated list)
prepend_include Prepend directories to search path
include Append directories to search path

3.1.2   Examples

<c:autoreconf force="1" install="1" warnings="cross,syntax,error"/>

Runs the autoreconf tool in the base directory with the option: force, install and 3 warning categories active: cross,syntax,error. This is equivalent to:

autoreconf --force --install --warnings=cross,syntax,error

3.2   <c:configure>

Executes a configure script as generated by Autoconf.

3.2.1   Parameters

Name Description
file Name of the configure script (defaults to "configure")
enable List of features to enable, separated by spaces.
disable List of features to disable, separated by spaces.
with List of packages to include, separated by spaces.
without List of packages to exclude, separated by spaces.
cflags Value of the CFLAGS variable to pass to the script.
cxxflags Value of the CXXFLAGS variable to pass to the script.

3.2.2   Examples

<c:configure enable="threadsafe" cflags="-O"/>

Runs the configure script in the base directory, enable the threadsafe feature, and passing -O as CFLAGS. This is equivalent to:

./configure --enable-threadsafe CFLAGS="-O"

3.2.3   Configuration

Parameter with will expand any package found in slave configuration:

[mylib]
path = /path/to/mylib

3.3   <c:gcov>

Run gcov to extract coverage data where available.

3.3.1   Parameters

Name Description
include List of glob patterns (separated by space) that specify which source files should be included in the coverage report
exclude List of glob patterns (separated by space) that specify which source files should be excluded from the coverage report
prefix Optional prefix name that is added to object files by the build system

3.4   <c:make>

Executes a Makefile.

3.4.1   Parameters

Name Description
target Name of the target to execute (defaults to "all")
file Path to the Makefile that should be used.
keep-going Whether make should try to continue even after encountering errors.
jobs Number of parallel jobs used by make.
directory Path of the directory in which make should be called.
args Any space separated arguments to pass to the makefile. Usually in the form: "parameter1=value1 parameter2=value2".

3.4.2   Examples

<c:make target="compile" file="build/Makefile" />

Runs the target "compile" of the Makefile located in the sub-directory build.

<c:make target="compile" file="build/Makefile" directory="work" args="coverage=1" />

Same as previous but execute the command in the work directory and call the makefile with the command line argument coverage=1.

3.4.3   Configuration

[make]
path = /path/to/(c|n)make

3.5   <c:cppunit>

Report the test output generated by the CppUnit unit testing framework. The output from CppUnit must be in XML format and in already, specified by the file argument of this recipe.

3.5.1   Parameters

Name Description
file Path to the cppunit XML output file.

3.5.2   Examples

<sh:exec executable="run_unit_tests" output="test_results.xml" />
<c:cppunit file="test_results.xml" />

Runs the program run_unit_tests to gather the data output by CppUnit in the test_results.xml file and then reports it.

4   Java Tools

A bundle of recipe commands that support tools commonly used by Java projects.

Namespace:http://bitten.edgewall.org/tools/java
Common prefix:java

4.1   <java:ant>

Runs an Ant build.

4.1.1   Parameters

Name Description
file Path of the build file, relative to the project source directory (default is build.xml).
target Name of the build target(s) to execute.
args Additional arguments to pass to Ant, separated by whitespace.
keep_going Tell Ant to continue even when errors are in encountered in the build.

4.1.2   Examples

<java:ant target="compile" />

Executes the target compile of the build.xml buildfile at the top of the project source directory.

4.1.3   Configuration

[ant]
home = /path/to/ant/dir

[java]
home = /path/to/java/dir

4.2   <java:cobertura>

Extract code coverage data from a Cobertura XML file.

4.2.1   Parameters

Name Description
file Path to the XML file generated by Cobertura

4.2.2   Examples

<java:cobertura file="build/cobertura.xml" />

Reads the specifid XML file, extracts the coverage data, and builds a coverage report to be sent to the build master.

4.3   <java:junit>

Extracts information about unit test results from a file in JUnit XML format.

4.3.1   Parameters

Name Description
file Path to the JUnit XML test results file. This can include wildcards, in which case all the file matching the pattern will be included.
srcdir Path of the directory unit test sources. Used to link the test cases to files.

The file attribute is required.

4.3.2   Examples

<java:junit file="build/tests/results/TEST-*.xml" srcdir="src/tests" />

Collects the test results from all files in the build/tests/results directory that match the pattern TEST-*.xml. Also, maps the class names in the results files to Java source files in the directory src/tests.

5   Mono Tools

A bundle of recipe commands that support tools commonly used by Mono/.NET projects.

Namespace:http://bitten.edgewall.org/tools/mono
Common prefix:mono

5.1   <mono:nunit>

Extracts information about unit test results from a files in NUnit XML format.

5.1.1   Parameters

Name Description
file Path to the NUnit XML test results file. This can include wildcards, in which case all the file matching the pattern will be included.

The file attribute is required.

5.1.2   Examples

<mono:nunit file="build/tests/TestResult.xml" />

6   PHP Tools

A bundle of recipe commands for PHP projects.

Namespace:http://bitten.edgewall.org/tools/php
Common prefix:php

6.1   <php:phing>

Runs a Phing build.

6.1.1   Parameters

Name Description
file Path of the build file, relative to the project source directory (default is build.xml).
target Name of the build target(s) to execute.
args Additional arguments to pass to Phing, separated by whitespace.
executable Phing executable program (default is phing).

6.1.2   Examples

<php:phing target="compile" />

Executes the target compile of the build.xml buildfile at the top of the project source directory.

6.2   <php:phpunit>

Extracts information from PHPUnit test results recorded in an XML file.

6.2.1   Parameters

Name Description
file Path to the XML results file, relative to the project source directory.

6.2.2   Examples

<php:phpunit file="build/test-results.xml"/>

Extracts the test results from the XML file located at build/test-results.xml.

6.3   <php:coverage>

Extracts coverage information from Phing's code coverage task XML file or from PHPUnit coverage-clover XML file.

6.3.1   Parameters

Name Description
file Path to the XML coverage file, relative to the project source directory.

6.3.2   Examples

<php:coverage file="build/coverage.xml" />

7   Python Tools

A bundle of recipe commands that support tools commonly used by Python projects.

Namespace:http://bitten.edgewall.org/tools/python
Common prefix:python

7.1   <python:exec>

Executes a Python script.

7.1.1   Parameters

Name Description
file Path of the script to execute, relative to the project source directory.
module Name of the Python module to execute.
function Name of the function in the Python module to run. Only works when also specifying the module attribute.
args Any arguments that should be passed to the script.
output Path to a file where any output by the script should be recorded.
timeout Limits the runtime of this command to the specified number of seconds, after which it will be terminated.

Either file or module must be specified.

7.1.2   Examples

<python:exec module="pylint.lint" output="pylint-report.txt" args="myproj" />

Executes Pylint on the module/package myproj and stores the output into a file named pylint-report.txt.

7.1.3   Configuration

[python]
path = /path/to/python

7.2   <python:distutils>

Executes a distutils script.

7.2.1   Parameters

Name Description
command The name of the distutils command that should be run
options Additional options to pass to the command, separated by spaces
timeout Limits the runtime of this command to the specified number of seconds, after which it will be terminated.

7.2.2   Examples

<python:distutils command="sdist" />

Instructs distutils to produce a source distribution.

<python:distutils command="unittest" options="
    --xml-output build/test-results.xml
    --coverage-summary build/test-coverage.txt
    --coverage-dir build/coverage
    --coverage-method trace"/>

Instructs distutils to run the unittest command (which is provided by Bitten), and passes the options needed to determine the output paths for test results and code coverage reports.

Option --coverage-method is one of trace, coverage or figleaf.

7.2.3   Configuration

[python]
path = /path/to/python

7.3   <python:unittest>

Extracts information from unittest results recorded in an XML file.

Note: This report must be used in conjunction with the distutils command "unittest" that comes with Bitten.

7.3.1   Parameters

Name Description
file Path to the XML results file, relative to the project source directory.

7.3.2   Examples

<python:unittest file="build/test-results.xml"/>

Extracts the test results from the XML file located at build/test-results.xml.

7.4   <python:trace>

Extracts coverage information recorded by the built-in Python module trace.py.

7.4.1   Parameters

Name Description
summary Path to the summary file written by trace.py, relative to the project source directory.
coverdir Path to the directory containing the coverage files written by trace.py, relative to the project source directory.
include List of glob patterns (separated by space) that specify which Python file should be included in the coverage report
exclude List of glob patterns (separated by space) that specify which Python file should be excluded from the coverage report

7.4.2   Examples

<python:trace summary="build/trace.out" coverdir="build/coverage" />

7.5   <python:coverage>

Extract data from a coverage.py run.

7.5.1   Parameters

Name Description
summary Path to the summary file with coverage.py information, relative to the project source directory.
coverdir Path to the directory containing per-module coverage details, relative to the project source directory.
include List of glob patterns (separated by space) that specify which Python file should be included in the coverage report
exclude List of glob patterns (separated by space) that specify which Python file should be excluded from the coverage report

7.5.2   Examples

<step id="test" description="Unittests with coverage.py information">
  <python:distutils command="unittest"
      options="--xml-output build/test-results.xml
               --coverage-summary build/test-coverage.txt
               --coverage-dir build/coverage
               --coverage-method coverage" />
  <python:unittest file="build/test-results.xml"/>
  <python:coverage summary="build/test-coverage.txt"
      coverdir="build/coverage"
      include="mypackage/*" exclude="*/tests/*" />
</step>

7.6   <python:figleaf>

Extracts coverage information recorded by Figleaf.

7.6.1   Parameters

Name Description
summary Path to the summary file written by figleaf, relative to the project source directory.
include List of glob patterns (separated by space) that specify which Python file should be included in the coverage report
exclude List of glob patterns (separated by space) that specify which Python file should be excluded from the coverage report

7.6.2   Examples

<step id="test" description="Unittests with Figleaf coverage">
  <python:distutils command="unittest"
      options="--xml-output build/test-results.xml
               --coverage-summary build/test-coverage.txt
               --coverage-dir build/coverage
               --coverage-method figleaf" />
  <python:unittest file="build/test-results.xml"/>
  <python:figleaf summary="build/test-coverage.txt"
      include="mypackage/*" exclude="*/tests/*" />
</step>

7.7   <python:pylint>

Extracts information from Pylint reports.

7.7.1   Parameters

Name Description
file Path to the file containing the Pylint output, relative to the project source directory.

7.7.2   Examples

<python:pylint file="build/pylint.out" />

8   Subversion Tools

A collection of recipe commands for working with the Subversion version control system. This commands are commonly used as the first step of a build recipe to actually pull the code that should be built from the repository.

Namespace:http://bitten.edgewall.org/tools/svn
Common prefix:svn

8.1   <svn:checkout>

Check out a working copy from a Subversion repository.

8.1.1   Parameters

Name Description
url URL of the repository.
path The path inside the repository that should be checked out. You should normally set this to ${path} so that the path of the build configuration is used.
revision The revision that should be checked out. You should normally set this to ${revision} so that the revision of the build is used.
dir Path specifying which directory the sources should be checked out to (defaults to '.').
verbose Whether to log the list of checked out files (defaults to False).
shared_path An optional shared directory to check the sources out in, which will be reused for each subsequent build. This is relative to the project directory, so for standard usage set it to something like ../trunk
username Username to pass for authentication (optional)
password Password to pass for authentication (optional)

8.1.2   Examples

<svn:checkout url="http://svn.example.org/repos/myproject/"
    path="${path}" revision="${revision}"/>

This checks out the a working copy into the current directory.

8.2   <svn:export>

Download a file or directory from a Subversion repository. This is similar to performing a checkout, but will not include the meta-data Subversion uses to connect the local working copy to the repository (i.e. it does not include the .svn directories.)

8.2.1   Parameters

Name Description
url URL of the repository.
path The path inside the repository that should be checked out. You should normally set this to ${path} so that the path of the build configuration is used.
revision The revision that should be checked out. You should normally set this to ${revision} so that the revision of the build is used.
dir Path specifying which directory the sources should be exported to (defaults to '.')
username Username to pass for authentication (optional)
password Password to pass for authentication (optional)

8.2.2   Examples

<svn:export url="http://svn.example.org/repos/myproject/"
    path="${path}" revision="${revision}"/>

This downloads the file or directory at ${path} from the Subversion repository at http://svn.example.org/repos/myproject/. Variables are used for the path and revision attributes so they are populated from the properties of the build and build configuration.

8.3   <svn:update>

Update an existing working copy from a Subversion repository to a specific revision.

8.3.1   Parameters

Name Description
revision The revision that should be checked out. You should normally set this to ${revision} so that the revision of the build is used.
dir Path specifying the directory containing the sources to be updated (defaults to '.')

8.3.2   Examples

<svn:update revision="${revision}"/>

This updates the working copy in the current directory. The revision is specified as a variable so that it is populated from the properties of the build.

9   XML Tools

A collection of recipe commands for XML processing.

Namespace:http://bitten.edgewall.org/tools/xml
Common prefix:x

9.1   <x:transform>

Apply an XSLT stylesheet .

Note: This command requires either libxslt (with Python bindings) or, on Windows platforms, MSXML (version 3 or later) to be installed on the slave machine.

9.1.1   Parameters

Name Description
src Path of the source XML file.
dest Path of the destition XML file.
stylesheet Path to the XSLT stylesheet file.

All these are interpreted relative to the project source directory.

9.1.2   Examples

<x:transform src="src.xml" dest="dest.xml" stylesheet="util/convert.xsl" />

This applies the stylesheet in util/convert.xsl to the source file src.xml, and writes the resulting XML document to dest.xml.

10   Mercurial Tools

A collection of recipe commands for working with Mercurial (hg) repositories.

Namespace:http://bitten.edgewall.org/tools/hg
Common prefix:hg

10.1   <hg:pull>

Pull changesets and updates a local Mercurial repository.

As the command depends on a pre-existing repository, bitten-slave must be started with --build-dir= option for locating and working with the repository. Also, seeing no remote location can be specified the repository .hg/hgrc configuration file needs a [paths] default = .... location defined.

10.1.1   Parameters

Name Description
revision The revision to update to (optional, defaults to tip).
dir Local subdirectory with repository (optional, defaults to '.').

Paths are interpreted relative to the project source directory.

10.1.2   Examples

<hg:pull revision="${revision}" dir="src" />

This updates the repository in src to the revision of the current build.