changeset 415:b4ec24092b54

Updated recipe command documentation.
author cmlenz
date Wed, 08 Aug 2007 12:24:13 +0000
parents aa34d82b2c9a
children ff35be7d2a5e
files bitten/build/javatools.py doc/commands.txt
diffstat 2 files changed, 192 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/bitten/build/javatools.py
+++ b/bitten/build/javatools.py
@@ -180,6 +180,12 @@
 
 
 def cobertura(ctxt, file_=None):
+    """Extract test coverage information from a Cobertura XML report.
+    
+    :param ctxt: the build context
+    :type ctxt: `Context`
+    :param file\_: path to the Cobertura XML output
+    """
     assert file_, 'Missing required attribute "file"'
 
     coverage = xmlio.Fragment()
--- a/doc/commands.txt
+++ b/doc/commands.txt
@@ -4,11 +4,13 @@
 Build Recipe Commands
 =====================
 
-Build recipes are represented by XML documents. This page describes what
+`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.
 
+.. _`build recipes`: recipes.html
+
 .. contents:: Contents
    :depth: 2
 .. sectnum::
@@ -166,6 +168,33 @@
 
 
 ------------
+``<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>``
 ------------
 
@@ -273,6 +302,34 @@
 project source directory.
 
 
+--------------------
+``<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>``
 ----------------
@@ -389,6 +446,17 @@
 
 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.
+
 
 ---------------------
 ``<python:unittest>``
@@ -481,6 +549,123 @@
   <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.                                       |
++--------------+-------------------------------------------------------------+
+
+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.                                       |
++--------------+-------------------------------------------------------------+
+
+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.                                       |
++--------------+-------------------------------------------------------------+
+
+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
 =========
 
Copyright (C) 2012-2017 Edgewall Software