= Build Recipe Commands Reference = [[PageOutline(2-3)]] As described on the [wiki:BuildRecipes 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 [milestone: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. === `` === Parse an XML file and send it to the master as a report with a given category. Use this command in conjunction with the `` or `` 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` === `` === 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''' === `` === 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 `execute` 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` === `` === 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 ==== {{{ }}} 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" }}} === `` === 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 ==== {{{ }}} 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` === `` === 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 ==== {{{ }}} Executes the target `compile` of the `build.xml` buildfile at the top of the project source directory. === `` === Extracts information about unit test results from a file in [http://junit.org/index.htm 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 ==== {{{ }}} 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 [http://www.python.org/ Python] projects. ''Namespace'':: `http://bitten.cmlenz.net/tools/python` ''Common prefix'':: `python` === `` === 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 ==== {{{ }}} Executes [http://www.logilab.org/projects/pylint Pylint] on the module/package “myproj” and stores the output into a file named `pylint-report.txt`. === `` === Executes a [http://docs.python.org/lib/module-distutils.html distutils] script. ==== Parameters ==== || Name || Description || || `command` || The name of the `distutils` command that should be run || ==== Examples ==== {{{ }}} Instructs `distutils` to produce a source distribution. === `` === Extracts information from [http://docs.python.org/lib/module-unittest.html unittest] results recorded in an XML file. ''Note: This report must be used in conjunction with the `distutils` command [source:trunk/bitten/util/testrunner.py unittest] that comes with Bitten.'' ==== Parameters ==== || Name || Description || || `file` || Path to the XML results file, relative to the project source directory. || ==== Examples ==== {{{ }}} Extracts the test results from the XML file located at `build/test-results.xml`. === `` === 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 ==== {{{ }}} === `` === Extracts information from [http://www.logilab.org/projects/pylint Pylint] reports. ==== Parameters ==== || Name || Description || || `file` || Path to the file containing the Pylint output, relative to the project source directory. || ==== Examples ==== {{{ }}} ---- == XML Tools == A collection of recipe commands for XML processing. ''Namespace'':: `http://bitten.cmlenz.net/tools/xml` ''Common prefix'':: `x` === `` === Apply an XSLT stylesheet . ''Note that this command requires either [http://xmlsoft.org/XSLT/ libxslt] (with [http://xmlsoft.org/XSLT/python.html 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 ==== {{{ }}} This applies the stylesheet in `util/convert.xsl` to the source file `src.xml`, and writes the resulting XML document to `dest.xml`.