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

----

== 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 `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`

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

----

== 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`

=== `<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. ||
|| `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 [http://www.logilab.org/projects/pylint Pylint] on the module/package “myproj” and stores the output into a file named `pylint-report.txt`.

=== `<python:distutils>` ===

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

{{{
 <python:distutils command="sdist" />
}}}

Instructs `distutils` to produce a source distribution.

=== `<python:unittest>` ===

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

{{{
 <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 [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 ====

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