Version 10 (modified by staffan, 18 years ago) (diff) |
---|
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.
<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.
Parameters
Name | Description |
file | Path to the cppunit XML output file. |
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.
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.