Mercurial > bitten > bitten-test
changeset 412:84b8cde2dfd4
Start with documentation.
| author | cmlenz |
|---|---|
| date | Tue, 07 Aug 2007 12:52:09 +0000 |
| parents | a169d2e96463 |
| children | fa72698e7477 |
| files | doc/commands.txt doc/index.txt doc/install.txt doc/recipes.txt setup.py |
| diffstat | 5 files changed, 725 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/commands.txt @@ -0,0 +1,529 @@ +.. -*- 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``.
new file mode 100644 --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,25 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +======= +Preface +======= + +.. image:: logo.png + :width: 538 + :height: 298 + :align: center + :alt: Bitten + :class: logo + +------------------------------- +Continuous Integration for Trac +------------------------------- + +Bitten is a Python-based framework for collecting various software metrics via +continuous integration. It builds on Trac to provide an integrated web-based +user interface. + + * `Installation <install.html>`_ + * `Build Recipes <recipes.html>`_ + * `Build Recipe Commands <commands.html>`_ + * `Generated API Documentation <api/index.html>`_
new file mode 100644 --- /dev/null +++ b/doc/install.txt @@ -0,0 +1,102 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +============ +Installation +============ + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +Prerequisites +============= + +Bitten is written in Python, so make sure that you have Python installed. +You'll need Python 2.3 or later. Also, make sure that setuptools_, version 0.6a2 +or later, is installed. + +.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools + +If that's taken care of, you just need to download and unpack the Bitten +distribution, and execute the command:: + + $ python setup.py install + +from the top of the directory where you unpacked (or checked out) the Bitten +code. Note that you may need administrator/root privileges for this step, as +it will by default attempt to install Bitten to the Python site-packages +directory on your system. + +It's also a good idea to run the unit tests at this point, to make sure that +the code works as expected on your platform:: + + $ python setup.py test + + +What's left to do now depends on whether you want to use the build master and +web interface, or just the build slave. In the latter case, you're already +done. You might need to install software that the build of your project +requires, but the Bitten build slave itself doesn't require anything extra. + +For the build master and web interface, you'll need to install Trac 0.10 or +later. Please refer to the Trac documentation for information on how it is +installed. + + +Build Master Configuration +========================== + +Once both Bitten and Trac are installed and working, you'll have to introduce +Bitten to your Trac project environment. If you don't have a Trac project +set up yet, you'll need to do so in order to use Bitten. + +If you already have a Trac project environment, the Bitten plugin needs to be +explicitly enabled in the Trac configuration. This is done by adding it to the +[components] section in /path/to/projenv/conf/trac.ini: + +.. code-block:: ini + + [components] + bitten.* = enabled + +The Trac web interface should now inform you with an error message that the +environment needs to be upgraded. To do this, run:: + + $ trac-admin /path/to/projenv upgrade + +This will create the database tables and directories that Bitten requires. +You probably also want to grant permissions to someone (such as yourself) +to manage build configurations, and allow anonymous users to view the +status and results of builds:: + + $ trac-admin /path/to/projenv permission add anonymous BUILD_EXEC + $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW + $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN + +You should now see an additional tab labeled "Build Status" in the Trac +navigation bar. This link will take you to the list of build configurations, +which at this point is of course empty. If you've set up permissions +correctly as described previously, you should see a button for adding new +build configurations. Click that button and fill out the form. Also, add +at least one target platform after saving the configuration. Last but not +least, you'll have to "activate" the build configuration. + + +Running the Build Slave +======================= + +The build slave can be run on any machine that can connect to the machine +on which the build master is running. The installation of Bitten should have put +a `bitten-slave` executable on your path. If the script is not on your path, +look for it in the `bin` or `scripts` subdirectory of your Python installation. + +To get a list of options for the build slave, execute it with the `--help` +option:: + + $ bitten-slave --help + +To run the build slave against a Bitten-enabled Trac site installed at +http://myproject.example.org/trac, you'd run:: + + $ bitten-slave http://myproject.example.org/trac/builds
new file mode 100644 --- /dev/null +++ b/doc/recipes.txt @@ -0,0 +1,59 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +============= +Build Recipes +============= + +A build recipe tells a build slave how a project is to be built. It consists of +multiple build steps, each defining a command to execute, and where artifacts +can be found after that command has successfully completed. + +Build recipes are intended to supplement existing project build files (such as +Makefiles), not to replace them. In general, a recipe will be much simpler than +the build file itself, because it doesn't deal with all the details of the +build. It just automates the execution of the build and lets the build slave +locate any artifacts and metrics data generated in the course of the build. + +A recipe can and should split the build into multiple separate steps so that the +build slave can provide better status reporting to the build master while the +build is still in progress. This is important for builds that might take long to +execute. In addition, build steps help organize the build results for a more +structured presentation. + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +File Format +=========== + +Build recipes are stored internally in an XML-based format. Recipe documents +have a single ``<build>`` root element with one or more ``<step>`` child +elements. The steps are executed in the order they appear in the recipe. + +A ``<step>`` element will consist of any number of commands and reports. Most of +these elements are declared in XML namespaces, where the namespace URI defines +a collection of related commands. + +.. code-block:: xml + + <build xmlns:python="http://bitten.cmlenz.net/tools/python"> + + <step id="build" description="Compile to byte code"> + <python:distutils command="build"/> + </step> + + <step id="test" description="Run unit tests"> + <python:distutils command="unittest"/> + <python:unittest file="build/test-results.xml"/> + <python:trace summary="build/test-coverage.txt" + coverdir="build/coverage" include="trac*" exclude="*.tests.*"/> + </step> + + </build> + +See `Build Recipe Commands`_ for a comprehensive reference of the commands +available by default. + +.. _`build recipe commands`: commands.html
--- a/setup.py +++ b/setup.py @@ -9,10 +9,18 @@ # you should have received as part of this distribution. The terms # are also available at http://bitten.edgewall.org/wiki/License. +import os from setuptools import setup, find_packages +import sys from bitten.util.testrunner import unittest +sys.path.append(os.path.join('doc', 'common')) +try: + from doctools import build_doc, test_doc +except ImportError: + build_doc = test_doc = None + NS = 'http://bitten.cmlenz.net/tools/' setup( @@ -71,5 +79,6 @@ ] }, - cmdclass = {'unittest': unittest} + cmdclass = {'build_doc': build_doc, 'test_doc': test_doc, + 'unittest': unittest} )