Mercurial > bitten > bitten-test
view doc/commands.txt @ 599:b76e6accad72
0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
| author | osimons |
|---|---|
| date | Thu, 30 Jul 2009 09:47:48 +0000 |
| parents | 4c3d43adaa48 |
| children | f3bb52da9e3c |
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, and any `runtime configuration`_ supported by these commands. Please note, though, that third-party packages can add additional commands, which would then be documented by that third party. .. _`build recipes`: recipes.html .. _`runtime configuration`: configure.html .. 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:autoreconf>`` ------------------ Executes ths autotool autoreconf. Parameters ---------- :param force: consider all files obsolete :param install: copy missing auxiliary files :param symlink: install symbolic links instead of copies :param warnings: report the warnings falling in CATEGORY :prepend_include: prepend directories to search path :include: append directories to search path +--------------+-------------------------------------------------------------+ | Name | Description | +==============+=============================================================+ | ``force`` | Consider all files obsolete | +--------------+-------------------------------------------------------------+ | ``install`` | Copy missing auxiliary files | +--------------+-------------------------------------------------------------+ | ``symlink`` | Install symbolic links instead of copies | +--------------+-------------------------------------------------------------+ | ``warnings`` | Report the warnings related to category | | | (which can actually be a comma separated list) | +--------------+-------------------------------------------------------------+ | ``prepend_include`` | Prepend directories to search path | +--------------+-------------------------------------------------------------+ | ``include`` | Append directories to search path | +--------------+-------------------------------------------------------------+ Examples -------- .. code-block:: xml <c:autoreconf force="1" install="1" warnings="cross,syntax,error"/> Runs the ``autoreconf`` tool in the base directory with the option: force, install and 3 warning categories active: cross,syntax,error. This is equivalent to:: autoreconf --force --install --warnings=cross,syntax,error ----------------- ``<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" Configuration ------------- Parameter ``with`` will expand any package found in slave configuration: .. code-block:: ini [mylib] path = /path/to/mylib ------------ ``<c:gcov>`` ------------ Run gcov_ to extract coverage data where available. .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov-Intro.html Parameters ---------- +--------------+------------------------------------------------------------+ | Name | Description | +==============+============================================================+ | ``include`` | List of glob patterns (separated by space) that specify | | | which source files should be included in the coverage | | | report | +--------------+------------------------------------------------------------+ | ``exclude`` | List of glob patterns (separated by space) that specify | | | which source files should be excluded from the coverage | | | report | +--------------+------------------------------------------------------------+ | ``prefix`` | Optional prefix name that is added to object files by the | | | build system | +--------------+------------------------------------------------------------+ ------------ ``<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. | +----------------+-----------------------------------------------------------+ | ``jobs`` | Number of parallel jobs used by make. | +----------------+-----------------------------------------------------------+ | ``directory`` | Path of the directory in which make should be called. | +----------------+-----------------------------------------------------------+ | ``args`` | Any space separated arguments to pass to the makefile. | | | Usually in the form: | | | ``"parameter1=value1 parameter2=value2"``. | +----------------+-----------------------------------------------------------+ Examples -------- .. code-block:: xml <c:make target="compile" file="build/Makefile" /> Runs the target "compile" of the ``Makefile`` located in the sub-directory ``build``. .. code-block:: xml <c:make target="compile" file="build/Makefile" directory="work" args="coverage=1" /> Same as previous but execute the command in the ``work`` directory and call the makefile with the command line argument ``coverage=1``. Configuration ------------- .. code-block:: ini [make] path = /path/to/(c|n)make --------------- ``<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. Configuration ------------- .. code-block:: ini [ant] home = /path/to/ant/dir [java] home = /path/to/java/dir -------------------- ``<java:cobertura>`` -------------------- Extract code coverage data from a Cobertura_ XML file. .. _cobertura: http://cobertura.sourceforge.net/ Parameters ---------- +----------------+-----------------------------------------------------------+ | Name | Description | +================+===========================================================+ | ``file`` | Path to the XML file generated by Cobertura | +----------------+-----------------------------------------------------------+ Examples -------- .. code-block:: xml <java:cobertura file="build/cobertura.xml" /> Reads the specifid XML file, extracts the coverage data, and builds a coverage report to be sent to the build master. ---------------- ``<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`. Mono Tools ========== A bundle of recipe commands that support tools commonly used by Mono/.NET projects. :Namespace: ``http://bitten.cmlenz.net/tools/mono`` :Common prefix: ``mono`` ---------------- ``<mono:nunit>`` ---------------- Extracts information about unit test results from a files in NUnit_ XML format. .. _nunit: http://nunit.org/ Parameters ---------- +----------------+-----------------------------------------------------------+ | Name | Description | +================+===========================================================+ | ``file`` | Path to the NUnit XML test results file. This can include | | | wildcards, in which case all the file matching the | | | pattern will be included. | +----------------+-----------------------------------------------------------+ The ``file`` attribute is required. Examples -------- .. code-block:: xml <mono:nunit file="build/tests/TestResult.xml" /> PHP Tools ========= A bundle of recipe commands for PHP_ projects. :Namespace: ``http://bitten.cmlenz.net/tools/php`` :Common prefix: ``php`` .. _php: http://php.net/ --------------- ``<php:phing>`` --------------- Runs a Phing_ build. .. _phing: http://phing.info/ 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 Phing, separated by | | | whitespace. | +-------------------+-------------------------------------------------------+ | ``executable`` | Phing executable program (default is ``phing``). | +-------------------+-------------------------------------------------------+ Examples -------- .. code-block:: xml <php:phing target="compile" /> Executes the target ``compile`` of the ``build.xml`` buildfile at the top of the project source directory. ----------------- ``<php:phpunit>`` ----------------- Extracts information from PHPUnit_ test results recorded in an XML file. .. _phpunit: http://www.phpunit.de/ Parameters ---------- +----------------+-----------------------------------------------------------+ | Name | Description | +================+===========================================================+ | ``file`` | Path to the XML results file, relative to the project | | | source directory. | +----------------+-----------------------------------------------------------+ Examples -------- .. code-block:: xml <php:phpunit file="build/test-results.xml"/> Extracts the test results from the XML file located at ``build/test-results.xml``. ------------------ ``<php:coverage>`` ------------------ Extracts coverage information from Phing_'s code coverage task XML file or from PHPUnit_ coverage-clover XML file. Parameters ---------- +---------------+-----------------------------------------------------------+ | Name | Description | +===============+===========================================================+ | ``file`` | Path to the XML coverage file, relative to the project | | | source directory. | +---------------+-----------------------------------------------------------+ Examples -------- .. code-block:: xml <php:coverage file="build/coverage.xml" /> 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``. Configuration ------------- .. code-block:: ini [python] path = /path/to/python ---------------------- ``<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. .. code-block:: xml <python:distutils command="unittest" options=" --xml-output build/test-results.xml --coverage-summary build/test-coverage.txt --coverage-dir build/coverage"/> Instructs `distutils` to run the ``unittest`` command (which is provided by Bitten), and passes the options needed to determine the output paths for test results and code coverage reports. Configuration ------------- .. code-block:: ini [python] path = /path/to/python --------------------- ``<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" /> Subversion Tools ================ A collection of recipe commands for working with the Subversion_ version control system. This commands are commonly used as the first step of a build recipe to actually pull the code that should be built from the repository. .. _subversion: http://subversion.tigris.org/ :Namespace: ``http://bitten.cmlenz.net/tools/svn`` :Common prefix: ``svn`` ------------------ ``<svn:checkout>`` ------------------ Check out a working copy from a Subversion repository. Parameters ---------- +-----------------+-------------------------------------------------------------+ | Name | Description | +=================+=============================================================+ | ``url`` | URL of the repository. | +-----------------+-------------------------------------------------------------+ | ``path`` | The path inside the repository that should be checked out. | | | You should normally set this to ``${path}`` so that the | | | path of the build configuration is used. | +-----------------+-------------------------------------------------------------+ | ``revision`` | The revision that should be checked out. You should | | | normally set this to ``${revision}`` so that the revision | | | of the build is used. | +-----------------+-------------------------------------------------------------+ | ``dir`` | Path specifying which directory the sources should be | | | checked out to (defaults to '.'). | +-----------------+-------------------------------------------------------------+ | ``verbose`` | Whether to log the list of checked out files (defaults to | | | False). | +-----------------+-------------------------------------------------------------+ | ``shared_path`` | An optional shared directory to check the sources out in, | | | which will be reused for each subsequent build. This is | | | relative to the project directory, so for standard usage | | | set it to something like ``../trunk`` | +-----------------+-------------------------------------------------------------+ | ``username`` | Username to pass for authentication (optional) | +-----------------+-------------------------------------------------------------+ | ``password`` | Password to pass for authentication (optional) | +-----------------+-------------------------------------------------------------+ Examples -------- .. code-block:: xml <svn:checkout url="http://svn.example.org/repos/myproject/" path="${path}" revision="${revision}"/> This checks out the a working copy into the current directory. ---------------- ``<svn:export>`` ---------------- Download a file or directory from a Subversion repository. This is similar to performing a checkout, but will not include the meta-data Subversion uses to connect the local working copy to the repository (i.e. it does not include the ``.svn`` directories.) Parameters ---------- +--------------+-------------------------------------------------------------+ | Name | Description | +==============+=============================================================+ | ``url`` | URL of the repository. | +--------------+-------------------------------------------------------------+ | ``path`` | The path inside the repository that should be checked out. | | | You should normally set this to ``${path}`` so that the | | | path of the build configuration is used. | +--------------+-------------------------------------------------------------+ | ``revision`` | The revision that should be checked out. You should | | | normally set this to ``${revision}`` so that the revision | | | of the build is used. | +--------------+-------------------------------------------------------------+ | ``dir`` | Path specifying which directory the sources should be | | | exported to (defaults to '.') | +--------------+-------------------------------------------------------------+ | ``username`` | Username to pass for authentication (optional) | +--------------+-------------------------------------------------------------+ | ``password`` | Password to pass for authentication (optional) | +--------------+-------------------------------------------------------------+ Examples -------- .. code-block:: xml <svn:export url="http://svn.example.org/repos/myproject/" path="${path}" revision="${revision}"/> This downloads the file or directory at ``${path}`` from the Subversion repository at ``http://svn.example.org/repos/myproject/``. Variables are used for the ``path`` and ``revision`` attributes so they are populated from the properties of the build and build configuration. ---------------- ``<svn:update>`` ---------------- Update an existing working copy from a Subversion repository to a specific revision. Parameters ---------- +--------------+-------------------------------------------------------------+ | Name | Description | +==============+=============================================================+ | ``revision`` | The revision that should be checked out. You should | | | normally set this to ``${revision}`` so that the revision | | | of the build is used. | +--------------+-------------------------------------------------------------+ | ``dir`` | Path specifying the directory containing the sources to be | | | updated (defaults to '.') | +--------------+-------------------------------------------------------------+ Examples -------- .. code-block:: xml <svn:update revision="${revision}"/> This updates the working copy in the current directory. The revision is specified as a variable so that it is populated from the properties of the build. 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``. Mercurial Tools =============== A collection of recipe commands for working with Mercurial_ (hg) repositories. .. _mercurial: http://mercurial.selenic.com/ :Namespace: ``http://bitten.cmlenz.net/tools/hg`` :Common prefix: ``hg`` ------------- ``<hg:pull>`` ------------- Pull changesets and updates a local Mercurial repository. As the command depends on a pre-existing repository, bitten-slave must be started with ``--build-dir=`` option for locating and working with the repository. Parameters ---------- +----------------+-----------------------------------------------------------+ | Name | Description | +================+===========================================================+ | ``revision`` | The revision to update to (optional, defaults to tip). | +----------------+-----------------------------------------------------------+ | ``dir`` | Local subdirectory with repository (optional, | | | defaults to '.'). | +----------------+-----------------------------------------------------------+ Paths are interpreted relative to the project source directory. Examples -------- .. code-block:: xml <hg:pull revision="${revision}" dir="src" /> This updates the repository in ``src`` to the revision of the current build.