cmlenz@412: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@412: 
cmlenz@412: =====================
cmlenz@412: Build Recipe Commands
cmlenz@412: =====================
cmlenz@412: 
cmlenz@415: `Build recipes`_ are represented by XML documents. This page describes what
cmlenz@412: commands are generally available in recipes. Please note, though, that
cmlenz@412: third-party packages can add additional commands, which would then be
cmlenz@412: documented by that third party.
cmlenz@412: 
cmlenz@415: .. _`build recipes`: recipes.html
cmlenz@415: 
cmlenz@412: .. contents:: Contents
cmlenz@412:    :depth: 2
cmlenz@412: .. sectnum::
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Generic Commands
cmlenz@412: ================
cmlenz@412: 
cmlenz@412: These are commands that are used without a namespace prefix.
cmlenz@412: 
cmlenz@412: 
cmlenz@412: ------------
cmlenz@412: ``<report>``
cmlenz@412: ------------
cmlenz@412: 
cmlenz@412: Parse an XML file and send it to the master as a report with a given category.
cmlenz@412: Use this command in conjunction with the ``<sh:pipe>`` or ``<x:transform>``
cmlenz@412: commands to send custom reports to the build master.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | Name         | Description                                                 |
cmlenz@413: +==============+=============================================================+
cmlenz@413: | ``category`` | Category of the report (for example "test" or "coverage").  |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``file``     | Path to the XML file containing the report data, relative   |
cmlenz@413: |              | to the project directory.                                   |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Both parameters must be specified.
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Shell Tools
cmlenz@412: ===========
cmlenz@412: 
cmlenz@412: A bundle of generic tools that are not specific to any programming language or
cmlenz@412: tool-chain.
cmlenz@412: 
cmlenz@413: :Namespace: ``http://bitten.cmlenz.net/tools/sh``
cmlenz@413: :Common prefix: ``sh``
cmlenz@412: 
cmlenz@412: 
cmlenz@412: -------------
cmlenz@412: ``<sh:exec>``
cmlenz@412: -------------
cmlenz@412: 
cmlenz@412: Executes a program or script.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``executable`` | The name of the executable program.                       |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``file``       | Path to the script to execute, relative to the project    |
cmlenz@413: |                | directory                                                 |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``output``     | Path to the output file                                   |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``args``       | Any arguments to pass to the executable or script         |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Either ``executable`` or ``file`` must be specified.
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: TODO
cmlenz@412: 
cmlenz@412: 
cmlenz@412: -------------
cmlenz@412: ``<sh:pipe>``
cmlenz@412: -------------
cmlenz@412: 
cmlenz@412: Pipes the content of a file through a program or script.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``executable`` | The name of the executable program.                       |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``file``       | Path to the script to execute, relative to the project    |
cmlenz@413: |                | directory                                                 |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``input``      | Path to the input file                                    |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``output``     | Path to the output file                                   |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``args``       | Any arguments to pass to the executable or script         |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Either ``executable`` or ``file`` must be specified.
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: TODO
cmlenz@412: 
cmlenz@412: 
cmlenz@412: C/Unix Tools
cmlenz@412: ============
cmlenz@412: 
cmlenz@412: These commands provide support for tools commonly used for development of C/C++
cmlenz@412: applications on Unix platforms, such as ``make``.
cmlenz@412: 
cmlenz@413: :Namespace: ``http://bitten.cmlenz.net/tools/c``
cmlenz@413: :Common prefix: ``c``
cmlenz@412: 
cmlenz@412: 
wbell@487: ------------------
wbell@478: ``<c:autoreconf>``
wbell@487: ------------------
wbell@478: 
wbell@478: Executes ths autotool autoreconf.
wbell@478: 
wbell@478: Parameters
wbell@478: ----------
wbell@478: 
wbell@478:     :param force: consider all files obsolete
wbell@478:     :param install: copy missing auxiliary files
wbell@478:     :param symlink: install symbolic links instead of copies
wbell@478:     :param warnings: report the warnings falling in CATEGORY
wbell@478:     :prepend_include: prepend directories to search path
wbell@478:     :include: append directories to search path
wbell@478: 
wbell@478: 
wbell@478: +--------------+-------------------------------------------------------------+
wbell@478: | Name         | Description                                                 |
wbell@478: +==============+=============================================================+
wbell@478: | ``force``    | Consider all files obsolete                                 |
wbell@478: +--------------+-------------------------------------------------------------+
wbell@478: | ``install``  | Copy missing auxiliary files                                |
wbell@478: +--------------+-------------------------------------------------------------+
wbell@478: | ``symlink``  | Install symbolic links instead of copies                    |
wbell@478: +--------------+-------------------------------------------------------------+
wbell@487: | ``warnings`` | Report the warnings related to category                     |
wbell@487: |              | (which can actually be a comma separated list)              |
wbell@478: +--------------+-------------------------------------------------------------+
wbell@478: | ``prepend_include``  | Prepend directories to search path                  |
wbell@478: +--------------+-------------------------------------------------------------+
wbell@478: | ``include``   | Append directories to search path                          |
wbell@478: +--------------+-------------------------------------------------------------+
wbell@478: 
wbell@478: Examples
wbell@478: --------
wbell@478: 
wbell@478: .. code-block:: xml
wbell@478: 
wbell@478:   <c:autoreconf force="1" install="1" warnings="cross,syntax,error"/>
wbell@478: 
wbell@478: Runs the ``autoreconf`` tool in the base directory with the option: force, install
wbell@478: and 3 warning categories active: cross,syntax,error. This is equivalent to::
wbell@478: 
wbell@478:   autoreconf --force --install --warnings=cross,syntax,error
wbell@478: 
wbell@478: 
wbell@478: -----------------
cmlenz@412: ``<c:configure>``
cmlenz@412: -----------------
cmlenz@412: 
cmlenz@412: Executes a configure script as generated by Autoconf.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | Name         | Description                                                 |
cmlenz@413: +==============+=============================================================+
cmlenz@413: | ``file``     | Name of the configure script (defaults to "configure")      |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``enable``   | List of features to enable, separated by spaces.            |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``disable``  | List of features to disable, separated by spaces.           |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``with``     | List of packages to include, separated by spaces.           |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``without``  | List of packages to exclude, separated by spaces.           |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``cflags``   | Value of the `CFLAGS` variable to pass to the script.       |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``cxxflags`` | Value of the `CXXFLAGS` variable to pass to the script.     |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@432:   <c:configure enable="threadsafe" cflags="-O"/>
cmlenz@412: 
cmlenz@432: Runs the ``configure`` script in the base directory, enable the ``threadsafe``
cmlenz@432: feature, and passing ``-O`` as ``CFLAGS``. This is equivalent to::
cmlenz@412: 
cmlenz@412:   ./configure --enable-threadsafe CFLAGS="-O"
cmlenz@412: 
cmlenz@412: 
cmlenz@412: ------------
cmlenz@415: ``<c:gcov>``
cmlenz@415: ------------
cmlenz@415: 
cmlenz@415: Run gcov_ to extract coverage data where available.
cmlenz@415: 
cmlenz@415: .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov-Intro.html
cmlenz@415: 
cmlenz@415: Parameters
cmlenz@415: ----------
cmlenz@415: 
cmlenz@415: +--------------+------------------------------------------------------------+
cmlenz@415: | Name         | Description                                                |
cmlenz@415: +==============+============================================================+
cmlenz@415: | ``include``  | List of glob patterns (separated by space) that specify    |
cmlenz@415: |              | which source files should be included in the coverage      |
cmlenz@415: |              | report                                                     |
cmlenz@415: +--------------+------------------------------------------------------------+
cmlenz@415: | ``exclude``  | List of glob patterns (separated by space) that specify    |
cmlenz@415: |              | which source files should be excluded from the coverage    |
cmlenz@415: |              | report                                                     |
cmlenz@415: +--------------+------------------------------------------------------------+
cmlenz@415: | ``prefix``   | Optional prefix name that is added to object files by the  |
cmlenz@415: |              | build system                                               |
cmlenz@415: +--------------+------------------------------------------------------------+
cmlenz@415: 
cmlenz@415: 
cmlenz@415: ------------
cmlenz@412: ``<c:make>``
cmlenz@412: ------------
cmlenz@412: 
cmlenz@412: Executes a Makefile.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``target``     | Name of the target to execute (defaults to "all")         |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``file``       | Path to the Makefile that should be used.                 |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``keep-going`` | Whether `make` should try to continue even after          |
cmlenz@413: |                | encountering errors.                                      |
cmlenz@413: +----------------+-----------------------------------------------------------+
wbell@487: | ``jobs``       | Number of parallel jobs used by make.                     |
wbell@487: +----------------+-----------------------------------------------------------+
wbell@487: | ``directory``  | Path of the directory in which make should be called.     |
wbell@487: +----------------+-----------------------------------------------------------+
wbell@487: | ``args``       | Any space separated arguments to pass to the makefile.    | 
wbell@487: |                | Usually in the form:                                      |
wbell@487: |                | ``"parameter1=value1 parameter2=value2"``.                |
wbell@487: +----------------+-----------------------------------------------------------+
wbell@487: 
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <c:make target="compile" file="build/Makefile" />
cmlenz@412: 
cmlenz@412: Runs the target "compile" of the ``Makefile`` located in the sub-directory
cmlenz@412: ``build``.
cmlenz@412: 
wbell@487: .. code-block:: xml
wbell@487: 
wbell@487:   <c:make target="compile" file="build/Makefile" directory="work" args="coverage=1" />
wbell@487: 
wbell@487: Same as previous but execute the command in the ``work`` directory and call
wbell@487: the makefile with the command line argument ``coverage=1``.
cmlenz@412: 
cmlenz@412: ---------------
cmlenz@412: ``<c:cppunit>``
cmlenz@412: ---------------
cmlenz@412: 
cmlenz@412: Report the test output generated by the CppUnit_ unit testing framework. The
cmlenz@412: output from CppUnit must be in XML format and in already, specified by the
cmlenz@412: ``file`` argument of this recipe.
cmlenz@412: 
cmlenz@412: .. _cppunit: http://cppunit.sourceforge.net
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``file``       | Path to the cppunit XML output file.                      |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <sh:exec executable="run_unit_tests" output="test_results.xml" />
cmlenz@412:   <c:cppunit file="test_results.xml" />
cmlenz@412: 
cmlenz@412: Runs the program ``run_unit_tests`` to gather the data output by CppUnit in the
cmlenz@412: ``test_results.xml`` file and then reports it.
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Java Tools
cmlenz@412: ==========
cmlenz@412: 
cmlenz@412: A bundle of recipe commands that support tools commonly used by Java projects.
cmlenz@412: 
cmlenz@413: :Namespace: ``http://bitten.cmlenz.net/tools/java``
cmlenz@413: :Common prefix: ``java``
cmlenz@412: 
cmlenz@412: 
cmlenz@412: --------------
cmlenz@412: ``<java:ant>``
cmlenz@412: --------------
cmlenz@412: 
cmlenz@412: Runs an Ant_ build.
cmlenz@412: 
cmlenz@412: .. _ant: http://ant.apache.org/
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``file``       | Path of the build file, relative to the project source    |
cmlenz@413: |                | directory (default is ``build.xml``).                     |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``target``     | Name of the build target(s) to execute.                   |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``args``       | Additional arguments to pass to Ant, separated by         |
cmlenz@413: |                | whitespace.                                               |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``keep_going`` | Tell Ant to continue even when errors are in encountered  |
cmlenz@413: |                | in the build.                                             |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <java:ant target="compile" />
cmlenz@412: 
cmlenz@432: Executes the target ``compile`` of the ``build.xml`` buildfile at the top of the
cmlenz@412: project source directory.
cmlenz@412: 
cmlenz@412: 
cmlenz@415: --------------------
cmlenz@415: ``<java:cobertura>``
cmlenz@415: --------------------
cmlenz@415: 
cmlenz@415: Extract code coverage data from a Cobertura_ XML file.
cmlenz@415: 
cmlenz@415: .. _cobertura: http://cobertura.sourceforge.net/
cmlenz@415: 
cmlenz@415: Parameters
cmlenz@415: ----------
cmlenz@415: 
cmlenz@415: +----------------+-----------------------------------------------------------+
cmlenz@415: | Name           | Description                                               |
cmlenz@415: +================+===========================================================+
cmlenz@415: | ``file``       | Path to the XML file generated by Cobertura               |
cmlenz@415: +----------------+-----------------------------------------------------------+
cmlenz@415: 
cmlenz@415: Examples
cmlenz@415: --------
cmlenz@415: 
cmlenz@415: .. code-block:: xml
cmlenz@415: 
cmlenz@415:   <java:cobertura file="build/cobertura.xml" />
cmlenz@415: 
cmlenz@415: Reads the specifid XML file, extracts the coverage data, and builds a coverage
cmlenz@415: report to be sent to the build master.
cmlenz@415: 
cmlenz@415: 
cmlenz@412: ----------------
cmlenz@412: ``<java:junit>``
cmlenz@412: ----------------
cmlenz@412: 
cmlenz@412: Extracts information about unit test results from a file in JUnit_ XML format.
cmlenz@412: 
cmlenz@412: .. _junit: http://junit.org/index.htm
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``file``       | Path to the JUnit XML test results file. This can include |
cmlenz@413: |                | wildcards, in which case all the file matching the        |
cmlenz@413: |                | pattern will be included.                                 |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``srcdir``     | Path of the directory unit test sources. Used to link the |
cmlenz@413: |                | test cases to files.                                      |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: The ``file`` attribute is required.
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <java:junit file="build/tests/results/TEST-*.xml" srcdir="src/tests" />
cmlenz@412: 
cmlenz@412: Collects the test results from all files in the `build/tests/results` directory
cmlenz@412: that match the pattern `TEST-*.xml`. Also, maps the class names in the results
cmlenz@412: files to Java source files in the directory `src/tests`.
cmlenz@412: 
cmlenz@412: 
cmlenz@416: PHP Tools
cmlenz@416: =========
cmlenz@416: 
cmlenz@416: A bundle of recipe commands for PHP_ projects.
cmlenz@416: 
cmlenz@416: :Namespace: ``http://bitten.cmlenz.net/tools/php``
cmlenz@416: :Common prefix: ``php``
cmlenz@416: 
cmlenz@416: .. _php: http://php.net/
cmlenz@416: 
cmlenz@422: ---------------
cmlenz@422: ``<php:phing>``
cmlenz@422: ---------------
cmlenz@416: 
cmlenz@416: Runs a Phing_ build.
cmlenz@416: 
cmlenz@416: .. _phing: http://phing.info/
cmlenz@416: 
cmlenz@416: Parameters
cmlenz@416: ----------
cmlenz@416: 
cmlenz@416: +-------------------+-------------------------------------------------------+
cmlenz@416: | Name              | Description                                           |
cmlenz@416: +===================+=======================================================+
cmlenz@416: | ``file``          | Path of the build file, relative to the project       |
cmlenz@416: |                   | source directory (default is ``build.xml``).          |
cmlenz@416: +-------------------+-------------------------------------------------------+
cmlenz@416: | ``target``        | Name of the build target(s) to execute.               |
cmlenz@416: +-------------------+-------------------------------------------------------+
cmlenz@416: | ``args``          | Additional arguments to pass to Phing, separated by   |
cmlenz@416: |                   | whitespace.                                           |
cmlenz@416: +-------------------+-------------------------------------------------------+
cmlenz@416: | ``executable``    | Phing executable program (default is ``phing``).      |
cmlenz@416: +-------------------+-------------------------------------------------------+
cmlenz@416: 
cmlenz@416: 
cmlenz@416: Examples
cmlenz@416: --------
cmlenz@416: 
cmlenz@416: .. code-block:: xml
cmlenz@416: 
cmlenz@416:   <php:phing target="compile" />
cmlenz@416: 
cmlenz@416: Executes the target ``compile`` of the ``build.xml`` buildfile at the top of the
cmlenz@416: project source directory.
cmlenz@416: 
cmlenz@416: 
cmlenz@416: -----------------
cmlenz@416: ``<php:phpunit>``
cmlenz@416: -----------------
cmlenz@416: 
cmlenz@416: Extracts information from PHPUnit_ test results recorded in an XML file.
cmlenz@416: 
cmlenz@416: .. _phpunit: http://www.phpunit.de/
cmlenz@416: 
cmlenz@416: Parameters
cmlenz@416: ----------
cmlenz@416: 
cmlenz@416: +----------------+-----------------------------------------------------------+
cmlenz@416: | Name           | Description                                               |
cmlenz@416: +================+===========================================================+
cmlenz@416: | ``file``       | Path to the XML results file, relative to the project     |
cmlenz@416: |                | source directory.                                         |
cmlenz@416: +----------------+-----------------------------------------------------------+
cmlenz@416: 
cmlenz@416: Examples
cmlenz@416: --------
cmlenz@416: 
cmlenz@416: .. code-block:: xml
cmlenz@416: 
cmlenz@416:   <php:phpunit file="build/test-results.xml"/>
cmlenz@416: 
cmlenz@416: Extracts the test results from the XML file located at
cmlenz@416: ``build/test-results.xml``.
cmlenz@416: 
cmlenz@416: 
cmlenz@416: ------------------
cmlenz@416: ``<php:coverage>``
cmlenz@416: ------------------
cmlenz@416: 
cmlenz@416: Extracts coverage information Phing_'s code coverage task recorded in an XML
cmlenz@416: file.
cmlenz@416: 
cmlenz@416: Parameters
cmlenz@416: ----------
cmlenz@416: 
cmlenz@416: +---------------+-----------------------------------------------------------+
cmlenz@416: | Name          | Description                                               |
cmlenz@416: +===============+===========================================================+
cmlenz@416: | ``file``      | Path to the XML coverage file, relative to the project    |
cmlenz@416: |               | source directory.                                         |
cmlenz@416: +---------------+-----------------------------------------------------------+
cmlenz@416: 
cmlenz@416: Examples
cmlenz@416: --------
cmlenz@416: 
cmlenz@416: .. code-block:: xml
cmlenz@416: 
cmlenz@416:   <php:coverage file="build/coverage.xml" />
cmlenz@416: 
cmlenz@416: 
cmlenz@412: Python Tools
cmlenz@412: ============
cmlenz@412: 
cmlenz@412: A bundle of recipe commands that support tools commonly used by Python_
cmlenz@412: projects.
cmlenz@412: 
cmlenz@413: :Namespace: ``http://bitten.cmlenz.net/tools/python``
cmlenz@413: :Common prefix: ``python``
cmlenz@412: 
cmlenz@412: .. _python: http://www.python.org/
cmlenz@412: 
cmlenz@412: 
cmlenz@412: -----------------
cmlenz@412: ``<python:exec>``
cmlenz@412: -----------------
cmlenz@412: 
cmlenz@412: Executes a Python script.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``file``       | Path of the script to execute, relative to the project    |
cmlenz@413: |                | source directory.                                         |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``module``     | Name of the Python module to execute.                     |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``function``   | Name of the function in the Python module to run. Only    |
cmlenz@413: |                | works when also specifying the `module` attribute.        |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``args``       | Any arguments that should be passed to the script.        |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``output``     | Path to a file where any output by the script should be   |
cmlenz@413: |                | recorded.                                                 |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Either `file` or `module` must be specified.
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <python:exec module="pylint.lint" output="pylint-report.txt" args="myproj" />
cmlenz@412: 
cmlenz@412: Executes Pylint_ on the module/package ``myproj`` and stores the output into a
cmlenz@412: file named ``pylint-report.txt``.
cmlenz@412: 
cmlenz@412: 
cmlenz@412: ----------------------
cmlenz@412: ``<python:distutils>``
cmlenz@412: ----------------------
cmlenz@412: 
cmlenz@412: Executes a distutils_ script.
cmlenz@412: 
cmlenz@412: .. _distutils: http://docs.python.org/lib/module-distutils.html
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | `command`      | The name of the `distutils` command that should be run    |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | `options`      | Additional options to pass to the command, separated by   |
cmlenz@413: |                | spaces                                                    |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <python:distutils command="sdist" />
cmlenz@412: 
cmlenz@412: Instructs `distutils` to produce a source distribution.
cmlenz@412: 
cmlenz@415: .. code-block:: xml
cmlenz@415: 
cmlenz@415:   <python:distutils command="unittest" options="
cmlenz@415:       --xml-output build/test-results.xml
cmlenz@415:       --coverage-summary build/test-coverage.txt
cmlenz@415:       --coverage-dir build/coverage"/>
cmlenz@415: 
cmlenz@415: Instructs `distutils` to run the ``unittest`` command (which is provided by
cmlenz@415: Bitten), and passes the options needed to determine the output paths for test
cmlenz@415: results and code coverage reports.
cmlenz@415: 
cmlenz@412: 
cmlenz@412: ---------------------
cmlenz@412: ``<python:unittest>``
cmlenz@412: ---------------------
cmlenz@412: 
cmlenz@412: Extracts information from unittest_ results recorded in an XML file.
cmlenz@412: 
cmlenz@412: .. _unittest: http://docs.python.org/lib/module-unittest.html
cmlenz@412: .. note:: This report must be used in conjunction with the ``distutils`` command
cmlenz@412:           "unittest" that comes with Bitten.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``file``       | Path to the XML results file, relative to the project     |
cmlenz@413: |                | source directory.                                         |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <python:unittest file="build/test-results.xml"/>
cmlenz@412: 
cmlenz@412: Extracts the test results from the XML file located at
cmlenz@412: ``build/test-results.xml``.
cmlenz@412: 
cmlenz@412: 
cmlenz@412: ------------------
cmlenz@412: ``<python:trace>``
cmlenz@412: ------------------
cmlenz@412: 
cmlenz@412: Extracts coverage information recorded by the built-in Python module
cmlenz@412: ``trace.py``.
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | Name         | Description                                                 |
cmlenz@413: +==============+=============================================================+
cmlenz@413: | ``summary``  | Path to the summary file written by ``trace.py``,           |
cmlenz@413: |              | relative to the project source directory.                   |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``coverdir`` | Path to the directory containing the coverage files written |
cmlenz@413: |              | by ``trace.py``, relative to the project source directory.  |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``include``  | List of glob patterns (separated by space) that specify     |
cmlenz@413: |              | which Python file should be included in the coverage report |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | ``exclude``  | List of glob patterns (separated by space) that specify     |
cmlenz@413: |              | which Python file should be excluded from the coverage      |
cmlenz@413: |              | report                                                      |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <python:trace summary="build/trace.out" coverdir="build/coverage" />
cmlenz@412: 
cmlenz@412: -------------------
cmlenz@412: ``<python:pylint>``
cmlenz@412: -------------------
cmlenz@412: 
cmlenz@412: Extracts information from Pylint_ reports.
cmlenz@412: 
cmlenz@412: .. _pylint: http://www.logilab.org/projects/pylint
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@413: | Name         | Description                                                 |
cmlenz@413: +==============+=============================================================+
cmlenz@413: | ``file``     | Path to the file containing the Pylint output, relative to  |
cmlenz@413: |              | the project source directory.                               |
cmlenz@413: +--------------+-------------------------------------------------------------+
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <python:pylint file="build/pylint.out" />
cmlenz@412: 
cmlenz@412: 
cmlenz@415: Subversion Tools
cmlenz@415: ================
cmlenz@415: 
cmlenz@415: A collection of recipe commands for working with the Subversion_ version
cmlenz@415: control system. This commands are commonly used as the first step of a build
cmlenz@415: recipe to actually pull the code that should be built from the repository.
cmlenz@415: 
cmlenz@415: .. _subversion: http://subversion.tigris.org/
cmlenz@415: 
cmlenz@415: :Namespace: ``http://bitten.cmlenz.net/tools/svn``
cmlenz@415: :Common prefix: ``svn``
cmlenz@415: 
cmlenz@415: 
cmlenz@415: ------------------
cmlenz@415: ``<svn:checkout>``
cmlenz@415: ------------------
cmlenz@415: 
cmlenz@415: Check out a working copy from a Subversion repository.
cmlenz@415: 
cmlenz@415: Parameters
cmlenz@415: ----------
cmlenz@415: 
cmlenz@415: +--------------+-------------------------------------------------------------+
cmlenz@415: | Name         | Description                                                 |
cmlenz@415: +==============+=============================================================+
cmlenz@415: | ``url``      | URL of the repository.                                      |
cmlenz@415: +--------------+-------------------------------------------------------------+
cmlenz@415: | ``path``     | The path inside the repository that should be checked out.  |
cmlenz@415: |              | You should normally set this to ``${path}`` so that the     |
cmlenz@415: |              | path of the build configuration is used.                    |
cmlenz@415: +--------------+-------------------------------------------------------------+
cmlenz@415: | ``revision`` | The revision that should be checked out. You should         |
cmlenz@415: |              | normally set this to ``${revision}`` so that the revision   |
cmlenz@415: |              | of the build is used.                                       |
cmlenz@415: +--------------+-------------------------------------------------------------+
wbell@491: | ``dir``      | Path specifying which directory the sources should be       |
wbell@491: |              | checked out to (defaults to '.').                           |
wbell@491: +--------------+-------------------------------------------------------------+
wbell@491: | ``verbose``  | Whether to log the list of checked out files (defaults to   |
wbell@491: |              | False).                                                     |
wbell@491: +--------------+-------------------------------------------------------------+
wbell@491: 
cmlenz@415: 
cmlenz@415: Examples
cmlenz@415: --------
cmlenz@415: 
cmlenz@415: .. code-block:: xml
cmlenz@415: 
cmlenz@415:   <svn:checkout url="http://svn.example.org/repos/myproject/"
cmlenz@415:       path="${path}" revision="${revision}"/>
cmlenz@415: 
cmlenz@415: This checks out the a working copy into the current directory.
cmlenz@415: 
cmlenz@415: 
cmlenz@415: ----------------
cmlenz@415: ``<svn:export>``
cmlenz@415: ----------------
cmlenz@415: 
cmlenz@415: Download a file or directory from a Subversion repository. This is similar to
cmlenz@415: performing a checkout, but will not include the meta-data Subversion uses to
cmlenz@415: connect the local working copy to the repository (i.e. it does not include the
cmlenz@415: ``.svn`` directories.)
cmlenz@415: 
cmlenz@415: Parameters
cmlenz@415: ----------
cmlenz@415: 
cmlenz@415: +--------------+-------------------------------------------------------------+
cmlenz@415: | Name         | Description                                                 |
cmlenz@415: +==============+=============================================================+
cmlenz@415: | ``url``      | URL of the repository.                                      |
cmlenz@415: +--------------+-------------------------------------------------------------+
cmlenz@415: | ``path``     | The path inside the repository that should be checked out.  |
cmlenz@415: |              | You should normally set this to ``${path}`` so that the     |
cmlenz@415: |              | path of the build configuration is used.                    |
cmlenz@415: +--------------+-------------------------------------------------------------+
cmlenz@415: | ``revision`` | The revision that should be checked out. You should         |
cmlenz@415: |              | normally set this to ``${revision}`` so that the revision   |
cmlenz@415: |              | of the build is used.                                       |
cmlenz@415: +--------------+-------------------------------------------------------------+
wbell@491: | ``dir``      | Path specifying which directory the sources should be       |
wbell@491: |              | exported to (defaults to '.')                               |
wbell@491: +--------------+-------------------------------------------------------------+
cmlenz@415: 
cmlenz@415: Examples
cmlenz@415: --------
cmlenz@415: 
cmlenz@415: .. code-block:: xml
cmlenz@415: 
cmlenz@415:   <svn:export url="http://svn.example.org/repos/myproject/"
cmlenz@415:       path="${path}" revision="${revision}"/>
cmlenz@415: 
cmlenz@415: This downloads the file or directory at ``${path}`` from the Subversion
cmlenz@415: repository at ``http://svn.example.org/repos/myproject/``. Variables are used
cmlenz@415: for the ``path`` and ``revision`` attributes so they are populated from the
cmlenz@415: properties of the build and build configuration.
cmlenz@415: 
cmlenz@415: 
cmlenz@415: ----------------
cmlenz@415: ``<svn:update>``
cmlenz@415: ----------------
cmlenz@415: 
cmlenz@415: Update an existing working copy from a Subversion repository to a specific
cmlenz@415: revision.
cmlenz@415: 
cmlenz@415: Parameters
cmlenz@415: ----------
cmlenz@415: 
cmlenz@415: +--------------+-------------------------------------------------------------+
cmlenz@415: | Name         | Description                                                 |
cmlenz@415: +==============+=============================================================+
cmlenz@415: | ``revision`` | The revision that should be checked out. You should         |
cmlenz@415: |              | normally set this to ``${revision}`` so that the revision   |
cmlenz@415: |              | of the build is used.                                       |
cmlenz@415: +--------------+-------------------------------------------------------------+
wbell@491: | ``dir``      | Path specifying the directory containing the sources to be  |
wbell@491: |              | updated (defaults to '.')                                   |
wbell@491: +--------------+-------------------------------------------------------------+
cmlenz@415: 
cmlenz@415: Examples
cmlenz@415: --------
cmlenz@415: 
cmlenz@415: .. code-block:: xml
cmlenz@415: 
cmlenz@415:   <svn:update revision="${revision}"/>
cmlenz@415: 
cmlenz@415: This updates the working copy in the current directory. The revision is
cmlenz@415: specified as a variable so that it is populated from the properties of the
cmlenz@415: build.
cmlenz@415: 
cmlenz@415: 
cmlenz@412: XML Tools
cmlenz@412: =========
cmlenz@412: 
cmlenz@412: A collection of recipe commands for XML processing.
cmlenz@412: 
cmlenz@413: :Namespace: ``http://bitten.cmlenz.net/tools/xml``
cmlenz@413: :Common prefix: ``x``
cmlenz@412: 
cmlenz@412: 
cmlenz@412: -----------------
cmlenz@412: ``<x:transform>``
cmlenz@412: -----------------
cmlenz@412: 
cmlenz@412: Apply an XSLT stylesheet .
cmlenz@412: 
cmlenz@412: .. note:: that this command requires either libxslt_ (with `Python bindings`_)
cmlenz@412:           or, on Windows platforms, MSXML (version 3 or later) to be installed
cmlenz@412:           on the slave machine.
cmlenz@412: 
cmlenz@412: .. _libxslt: http://xmlsoft.org/XSLT/
cmlenz@412: .. _`python bindings`: http://xmlsoft.org/XSLT/python.html
cmlenz@412: 
cmlenz@412: Parameters
cmlenz@412: ----------
cmlenz@412: 
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | Name           | Description                                               |
cmlenz@413: +================+===========================================================+
cmlenz@413: | ``src``        | Path of the source XML file.                              |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``dest``       | Path of the destition XML file.                           |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@413: | ``stylesheet`` | Path to the XSLT stylesheet file.                         |
cmlenz@413: +----------------+-----------------------------------------------------------+
cmlenz@412: 
cmlenz@412: All these are interpreted relative to the project source directory.
cmlenz@412: 
cmlenz@412: Examples
cmlenz@412: --------
cmlenz@412: 
cmlenz@412: .. code-block:: xml
cmlenz@412: 
cmlenz@412:   <x:transform src="src.xml" dest="dest.xml" stylesheet="util/convert.xsl" />
cmlenz@412: 
cmlenz@412: This applies the stylesheet in ``util/convert.xsl`` to the source file
cmlenz@412: ``src.xml``, and writes the resulting XML document to ``dest.xml``.