Build Recipe Commands

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

Contents

• 1   Generic Commands
  • 1.1   <report>
• 2   Shell Tools
  • 2.1   <sh:exec>
  • 2.2   <sh:pipe>
• 3   C/Unix Tools
  • 3.1   <c:autoreconf>
  • 3.2   <c:configure>
  • 3.3   <c:gcov>
  • 3.4   <c:make>
  • 3.5   <c:cppunit>
• 4   Java Tools
  • 4.1   <java:ant>
  • 4.2   <java:cobertura>
  • 4.3   <java:junit>
• 5   PHP Tools
  • 5.1   <php:phing>
  • 5.2   <php:phpunit>
  • 5.3   <php:coverage>
• 6   Python Tools
  • 6.1   <python:exec>
  • 6.2   <python:distutils>
  • 6.3   <python:unittest>
  • 6.4   <python:trace>
  • 6.5   <python:pylint>
• 7   Subversion Tools
  • 7.1   <svn:checkout>
  • 7.2   <svn:export>
  • 7.3   <svn:update>
• 8   XML Tools
  • 8.1   <x:transform>

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.

2   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

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

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

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

3.1   <c:autoreconf>

Executes ths autotool autoreconf.

3.1.1   Parameters

param force:	consider all files obsolete
param install:	copy missing auxiliary files
param symlink:	install symbolic links instead of copies
param warnings:	report the warnings falling in CATEGORY
prepend_include:
	prepend directories to search path
include:	append directories to search path

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.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.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.cmlenz.net/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.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   PHP Tools

A bundle of recipe commands for PHP projects.

Namespace:	http://bitten.cmlenz.net/tools/php
Common prefix:	php

5.1   <php:phing>

Runs a Phing build.

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

5.1.2   Examples

<php:phing target="compile" />

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

5.2   <php:phpunit>

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

5.2.1   Parameters

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

5.2.2   Examples

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

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

5.3   <php:coverage>

Extracts coverage information Phing's code coverage task recorded in an XML file.

5.3.1   Parameters

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

5.3.2   Examples

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

6   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

6.1   <python:exec>

Executes a Python script.

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

Either file or module must be specified.

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

6.2   <python:distutils>

Executes a distutils script.

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

6.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"/>

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.

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

6.3.1   Parameters

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

6.3.2   Examples

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

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

6.4   <python:trace>

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

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

6.4.2   Examples

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

6.5   <python:pylint>

Extracts information from Pylint reports.

6.5.1   Parameters

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

6.5.2   Examples

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

7   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.cmlenz.net/tools/svn
Common prefix:	svn

7.1   <svn:checkout>

Check out a working copy from a Subversion repository.

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

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

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

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

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

7.3   <svn:update>

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

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

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

8   XML Tools

A collection of recipe commands for XML processing.

Namespace:	http://bitten.cmlenz.net/tools/xml
Common prefix:	x

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

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

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

---

See also: Documentation