<?xml version="1.0"?>
<document>

  <properties>
    <author email="vmassol@octo.com">Vincent Massol</author>
    <title>Maven Clover Plug-in Build File Documentation</title>
  </properties>

  <body>
    <section name="Maven Clover Plug-in Build File">
      <p>
        Maven utilizes <a href="http://ant.apache.org/">Ant</a>
        to provide users with an easy-to-use and familiar interface to
        manage projects that have been described with a valid Maven <a
        href="../project-descriptor.html">project descriptor</a>.
        The build files that Maven <a href="../../start/index.html">
        installs</a> are stored in <code>${maven.home}</code> directory.
      </p>
      <p>
        This document describes the Ant build file and targets
        that are available when using the Clover Plug-in with Maven.
      </p>
      <p>
        The current recommended approach to using Maven is to add
        delegators to these Maven-provided targets in your project's
        main build file.  This will enable you to use your existing
        build file with the additional Maven functionality.  In
        addition, it is also recommended that you load a standard set of
        property files.  The property files will setup your environment, 
        <code>${lib.repo}</code> and <code>${maven.home}</code>, and
        allow you to override Maven defaults properties.  Please refer
        to the <a href="../../start/integrate.html">Integration</a> document for
        more information on how to integrate these build targets into
        your project.
      </p>
      <p>
        The following table contains a brief overview of the
        build file that is installed as part of the Maven Clover Plug-in in the
        <code>${maven.home}/plugin/clover</code> directory. In addition,
        the various Ant targets in this file is discussed.
      </p>
      <table>
        <tr><th>Build File</th><th>Description</th></tr>
        <tr>
          <td><a href="#clover/build.xml">build.xml</a></td>
          <td>
            Contains targets to generate Clover test coverage reports.
          </td>
        </tr>
      </table>
      <p>
        The build file utilizes various properties for default and
        user-configurable settings.  All Clover Plug-in properties are described
        in the <a href="properties.html">Properties</a> document.
      
        The rest of this document assumes your project follows the standard 
        <a href="dirlayout.html">Directory Layout</a>; however, it is
        possible to override many of these defaults.
      </p>
    </section>
    <section name="clover/build.xml">
      <table>
        <tr><th>Target</th><th>Description</th></tr>
        <tr>
          <td><a href="#maven:clover-test">maven:clover-test</a></td>
          <td>Runs unit tests on Clover-instrumented code and generates 
              coverage data.</td>
        </tr>
        <tr>
          <td><a href="#maven:clover-report-html">maven:clover-report-html</a></td>
          <td>Generates HTML Clover Test coverage reports.</td>
        </tr>
        <tr>
          <td><a href="#maven:clover-report-swing">maven:clover-report-swing</a></td>
          <td>Run Clover Test coverage reports with the Swing viewer</td>
        </tr>
      </table>
      <p/>
      <subsection name="maven:clover-test">
        <p>
          This target instruments your code, runs your unit tests on it
          and generates a Clover database file. This target must be called
          prior to calling one of the report targets below.
        </p>
        <p>
          <strong>Note</strong> : There is a limitation in Clover 0.5b. The 
          test coverage results are written to Clover database on JVM shutdown
          only. Thus be careful to execute the <code>maven:clover-test</code>
          target separately from the <code>maven:clover-report-*</code> ones
          or the report will show a 0% coverage result! In other words, do not
          type "<code>ant maven:clover-test maven:clover-report-*</code>".
          Instead, do it in 2 JVM invocations : 
          "<code>ant maven:clover-tests</code>" and 
          "<code>ant maven:clover-report-*</code>".
        </p>
      </subsection>
      <subsection name="maven:clover-report-html">
        <p>
          Prior to running this target you should have called the
          <code>maven:clover-test</code> one which generates a test 
          result database file. This target generates an HTML report 
          from that database file. The report shows exactly what lines of 
          your code were exercised by your tests.
        </p>
      </subsection>
      <subsection name="maven:clover-report-swing">
        <p>
          Prior to running this target you should have called the
          <code>maven:clover-test</code> one which generates a test 
          result database file. This target runs a Swing viewer
          displaying the content of that database file.
        </p>
      </subsection>
    </section>
  </body>
</document>
