Build Recipe Commands Reference

As described on the page about build recipes, a recipe is stored as an XML document. This page describes what commands are available in recipes.

Note: the recipe format has changed since 0.4. You can find documentation about the previous format by looking at version 3 of this page (see the “page history” link above).

---

Generic Commands

These are commands that are used without a namespace prefix.

<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.

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.

---

Shell Tools

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

Namespace

http://bitten.cmlenz.net/tools/sh

Common prefix

sh

<sh:exec>

Executes a program or script.

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

Either execute or file must be specified.

Examples

TODO

<sh:pipe>

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

Parameters

Name	Default
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

Either executable or file must be specified.

Examples

TODO

---

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.cmlenz.net/tools/c

Common prefix

c

<c:configure>

Executes a configure script as generated by Autoconf.

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.

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"

<c:make>

Executes a Makefile.

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.

Examples

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

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

---

Java Tools

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

Namespace

http://bitten.cmlenz.net/tools/java

Common prefix

java

<java:ant>

Runs an Ant build.

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.

Examples

 <java:ant target="compile" />

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

<java:junit>

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

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.

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.

---

Python Tools

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

Namespace

http://bitten.cmlenz.net/tools/python

Common prefix

python

<python:exec>

Executes a Python script.

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.

Either file or module must be specified.

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.

<python:distutils>

Executes a ​distutils script.

Parameters

Name	Description
command	The name of the distutils command that should be run

Examples

 <python:distutils command="sdist" />

Instructs distutils to produce a source distribution.

<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.

Parameters

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

Examples

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

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

<python:trace>

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

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.

Examples

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

<python:pylint>

Extracts information from ​Pylint reports.

Parameters

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

Examples

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

---

XML Tools

A collection of recipe commands for XML processing.

Namespace

http://bitten.cmlenz.net/tools/xml

Common prefix

x

<x:transform>

Apply an XSLT stylesheet .

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

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.

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.