Mercurial > bitten > bitten-test
view doc/commands.txt @ 414:aa34d82b2c9a
The build slave can now run locally against a recipe file, which is useful for testing recipes. Simply pass the path to the recipe instead of the URL of the build master to the script.
| author | cmlenz |
|---|---|
| date | Wed, 08 Aug 2007 12:10:46 +0000 |
| parents | fa72698e7477 |
| children | b4ec24092b54 |
line wrap: on
line source
.. -*- mode: rst; encoding: utf-8 -*- ===================== 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:: Contents :depth: 2 .. sectnum:: 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 ``executable`` or ``file`` must be specified. Examples -------- TODO ------------- ``<sh:pipe>`` ------------- Pipes the content of a file through 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 | +----------------+-----------------------------------------------------------+ | ``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 -------- .. code-block:: xml <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 -------- .. code-block:: xml <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. .. _cppunit: http://cppunit.sourceforge.net Parameters ---------- +----------------+-----------------------------------------------------------+ | Name | Description | +================+===========================================================+ | ``file`` | Path to the cppunit XML output file. | +----------------+-----------------------------------------------------------+ Examples -------- .. code-block:: xml <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. .. _ant: http://ant.apache.org/ 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 -------- .. code-block:: xml <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. .. _junit: http://junit.org/index.htm 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 -------- .. code-block:: xml <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: http://www.python.org/ ----------------- ``<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 -------- .. code-block:: xml <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. .. _distutils: http://docs.python.org/lib/module-distutils.html 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 | +----------------+-----------------------------------------------------------+ Examples -------- .. code-block:: xml <python:distutils command="sdist" /> Instructs `distutils` to produce a source distribution. --------------------- ``<python:unittest>`` --------------------- Extracts information from unittest_ results recorded in an XML file. .. _unittest: http://docs.python.org/lib/module-unittest.html .. 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 -------- .. code-block:: xml <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 -------- .. code-block:: xml <python:trace summary="build/trace.out" coverdir="build/coverage" /> ------------------- ``<python:pylint>`` ------------------- Extracts information from Pylint_ reports. .. _pylint: http://www.logilab.org/projects/pylint Parameters ---------- +--------------+-------------------------------------------------------------+ | Name | Description | +==============+=============================================================+ | ``file`` | Path to the file containing the Pylint output, relative to | | | the project source directory. | +--------------+-------------------------------------------------------------+ Examples -------- .. code-block:: xml <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. .. _libxslt: http://xmlsoft.org/XSLT/ .. _`python bindings`: http://xmlsoft.org/XSLT/python.html 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 -------- .. code-block:: xml <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``.