<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
    <name>GroboCoverage Ant Tasks</name>
    <doc-version>$Date: 2004/03/15 22:31:14 $</doc-version>
    <author>Matt Albrecht</author>
</head>
<body>

<a name="tasks"><section>A Guide To The Ant Tasks</section></a>

<P>
The following is a listing of all ant tasks contained in this package.
</P>

<anttask name="coveragepostcompiler">
    <description>
    Recompiles the provided class files to a separate directory, and stores
    the compilation generated data (for use in report generation) to another
    directory.
    </description>
    <ant-nested-element name="fileset">
        <description>
        the <ant-link href="using.html#fileset">FileSet</ant-link> to use for
        defining all the class files to recompile.  Note that no matter what
        is specified in the file sets, only files ending in ".class"
        (case-insensitive) will be recompiled.  There may be multiple of these
        file sets specified.
        </description>
    </ant-nested-element>
    <ant-nested-element name="analysismodule">
        <description>
        Defines a single analysis module to use in the analysis of each
        class file that is recompiled.  An analysis module creates coverage
        details for the class specific to its measure, such as line-count or
        branch count.  Multiple of these modules may be specified.  Each
        analysis module will have its own report generated.
        </description>
        <ant-nested-element name="classpath">
            <description>
            Analysismodule's <i>classpath</i> attribute is a
            <ant-link href="using.html#path">PATH like structure</ant-link>
            and can also be set via a nested classpath element.
            </description>
        </ant-nested-element>
        <ant-parameter>
            <attribute>name</attribute>
            <description>the name of the analysis module to load.  The only
            current acceptable values are:
                <UL>
                <definition term="linecount">
                counts the source code line coverage.  This requires the
                line information to be stored in the class file.
                </definition>
                <definition term="bytecode">
                counts the coverage of the class file's bytecode.  This
                is the most detailed look at exactly what amount of code
                is and is not being covered, but can be hard to read.
                </definition>
                <definition term="branch">
                counts the coverage of each branch by looking at the
                bytecode branching instructions.
                </definition>
                <definition term="call-pair">
                counts the coverage of each method invocation.
                </definition>
                <definition term="function">
                counts the "function" or "method" entry coverage; when
                the execution enters a method, that method is marked as
                covered.
                </definition>
                </UL>
            </description>
            <required>One of <code>name</code> or <code>classname</code> must be specified</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>classname</attribute>
            <description>Loads a non-standard analysis module, using this
            parameter as a the fully-qualified class name of the analysis
            module class.  If this is specified, then it will use the
            classpathref parameter, embedded classpath element, or loaderref 
            parameter to reference the classpath from which to load the
            module, if any are provided.  If none are provided, then
            the classloader for the task will be used instead.
            </description>
            <required>One of <code>name</code> or <code>classname</code> must be specified</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>classpathref</attribute>
            <description>Reference to a classpath to use when looking up
                <code>classname</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>loaderRef</attribute>
            <description>the name of the loader that is used to load the
                class, constructed from the specified classpath.
                Use this to allow multiple tasks/types to be loaded with the
                same loader, so they can call each other.
            </description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    <ant-nested-element name="logsettings">
        <description>
         Sets up how the logs are generated by the covered classes.
         This allows for configuration of the
         <code>grobocoverage.properties</code> file (which tells the
         coverage-enabled classes everything they need
         during operation to run correctly), and generates that properties
         file for you.
        </description>
        <ant-parameter>
            <attribute>factory</attribute>
            <description>the factory class to handle the logging. If no
            package is specified, then this property will prepend
            "net.sourceforge.groboutils.codecoverage.v2.logger." to the
            given factory name. Currently, there are two types of loggers:
                <ol>
                    <definition term="DirectoryChannelLoggerFactory">(default)
                    This is the safest logger, but the slowest. On each
                    logging request, it opens the log file, writes the log
                    element, then closes the log file, all in a VM-wide
                    synchronized block. Using this logger, you will likely
                    see a large amount of disk access. The <code>logDir</code>
                    parameter (below) defines the directory to place all
                    the channel log data (default directory is
                    "./.cover-logs").</definition>
                    <definition term="CacheDirChannelLoggerFactory">
                    This is a faster logger. It keeps a sized cache of open
                    log files in memory, each log file being a buffered
                    file. This has a danger of possibly not closing or flushing
                    its open log files on VM shutdown. If the VM is JDK 1.3
                    compatible, the logger will add a shutdown hook to
                    attempt to close its opened files. Using this logger,
                    you should see large disk access when the VM ends.
                    It uses the <code>logDir</code> parameter (below) that
                    the <code>DirectoryChannelLoggerFactory</code> uses,
                    and also uses the <code>cachesize</code> parameter,
                    which defines the maximum number of opened files
                    stored in the cache per channel (default size is 25,
                    but you should match this to the limitations of the
                    operating system).
                    <p>
                    There's a pending issue with this logger (<a
                    href="https://sourceforge.net/tracker/index.php?func=detail&amp;aid=902884&amp;group_id=22594&amp;atid=375589"
                    >bug 902884</a>).
                    </p>
                    </definition>
                    <definition term="MinDirChannelLoggerFactory">
                    This operates identically to
                    <code>DirectoryChannelLoggerFactory</code>,
                    but caches the encountered covered items, and only
                    writes new elements to the log files.  This is
                    JDK 1.2 dependent, and may eat up lots of memory.  However,
                    for those that are encountering issues due to enormous
                    log files, moving to this logger should fix the problem.
                    Also, this should reduce file I/O.
                    </definition>
                </ol>
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>logDir</attribute>
            <description>the directory that all the coverage logging
            data will be put. Must match the report task's
            <code>logDir</code> parameter.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>cachesize</attribute>
            <description>the number of concurrent files to keep open.
            Only used by the <code>CacheDirChannelLoggerFactory</code>.
            </description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-parameter>
        <attribute>datadir</attribute>
        <description>the name of the directory to send the analysis module
        generated data to.  This same directory should be specified in the
        <tt>coveragereport</tt> task's <tt>datadir</tt> attribute as well.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>outclassdir</attribute>
        <description>The name of the directory in which the recompiled class
        files are saved.  This directory should <em>never</em> be confused with
        the original classes: these classes are slower and "fatter" than the
        originals.
        </description>
        <required>Yes</required>
    </ant-parameter>
    
    <ant-example>
        <source>
&lt;coveragepostcompiler
        outclassdir="coverage/classes"
        datadir="coverage/data"
        &gt;
    &lt;analysismodule name="linecount" /&gt;
    &lt;fileset dir="${dirs.classes}" /&gt;
    &lt;fileset dir="${dirs.classes2}"&gt;
        &lt;excludes name="dont/cover/these/*.class" /&gt;
    &lt;/fileset&gt;
    &lt;logsettings logdir="coverage/logs" /&gt;
&lt;/coveragepostcompiler&gt;
        </source>
        <description>
        Recompiles all the classes located in <tt>${dirs.classes}</tt> using
        the linecount analysis module, and recompiles all the classes from
        <code>${dirs.classes2}</code> except those in the
        <code>dont.cover.these</code> package.  All the recompiled classes are
        stored in <tt>coverage/classes</tt>, and the analysis
        module generated data is stored under the
        <tt>coverage/data</tt> directory.  The default logger factory
        (<code>DirectoryChannelLoggerFactory</code>) will be used during runs,
        outputting log data to <code>coverage/logs</code>.
        </description>
    </ant-example>
</anttask>

<BR />
<anttask name="coveragereport">
    <description>
    Generates an XML report describing all the coverage tallies for the
    classes that were logged during runtime execution.  The report combines
    the runtime coverage logs with the post-compilation generated data.  One
    report is created per analysis module.  Currently, this task supports
    all included channel outputs (<code>DirectoryChannelLoggerFactory</code>,
    <code>CacheDirChannelLoggerFactory</code>, and
    <code>MinDirChannelLoggerFactory</code>).
    </description>
    
    <ant-nested-element name="simplestyle">
        <description>
         Generates one HTML file for each analysis module<special-text>,
         which look something like
         <link name="CoverageReport-LineCount">this</link></special-text>.
        </description>
        <ant-parameter>
            <attribute>prefix</attribute>
            <description>The text to prepend all output HTML file names.
            The output name will look like
            <code><i>prefix</i>ModuleName<i>suffix</i></code>.  Default
            prefix is <code>CoverageReport-</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>suffix</attribute>
            <description>The text to append to all output HTML file names.
            The output name will look like
            <code><i>prefix</i>ModuleName<i>suffix</i></code>.  Default
            prefix is <code>CoverageReport-</code>.  Default suffix is
            <code>.html</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>destdir</attribute>
            <description>The output directory to place the HTML files.
            Default directory is <code>.</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>removeEmpty</attribute>
            <description>A boolean value.  This describes whether the
            output report should remove all methods and classes that don't
            have any code attributed to them (such as interfaces and
            abstract methods).  Default is <code>false</code>.
            </description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-nested-element name="sourcestyle">
        <description>
         Generates a JavaDoc-like collection of HTML files for all the
         analysis modules, linking the coverage reports to the source files.
         This report shows the contents of the source files and highlights
         whichever lines were not covered.
        </description>
        <ant-parameter>
            <attribute>title</attribute>
            <description>The title text to be placed on the top of every
            HTML file.  Default is <code>Summary Coverage Report</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>srcdir</attribute>
            <description>Directory containing the source files.
            </description>
            <required>Yes</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>destdir</attribute>
            <description>The output directory to place the HTML files.
            Default directory is <code>.</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>removeEmpty</attribute>
            <description>A boolean value.  This describes whether the
            output report should remove all methods and classes that don't
            have any code attributed to them (such as interfaces and
            abstract methods).  Default is <code>false</code>.
            </description>
            <required>No</required>
        </ant-parameter>
    
        <ant-nested-element name="srcdir">
            <description>
            In addition to the <code>srcdir</code> attribute, you can include
            multiple source directories for searching.  The first directory
            containing the source file will be used in the report.
            </description>
            <ant-parameter>
                <attribute>name</attribute>
                <description>The name of the directory containing a
                source tree.
                </description>
                <required>Yes</required>
            </ant-parameter>
        </ant-nested-element>
    </ant-nested-element>

    <ant-parameter>
        <attribute>datadir</attribute>
        <description>The name of the directory to read the analysis module
        generated data from.  This same directory should be specified in the
        <tt>coveragepostcompiler</tt> task's <tt>datadir</tt> attribute as
        well.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>logDir</attribute>
        <description>The name of the directory to read the log output
        generated from running the code.  This same directory should be
        specified in the <tt>grobocoverage.properties</tt> file.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>outdir</attribute>
        <description>The name of the directory that will contain the generated
        XML documents.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>reportfileprefix</attribute>
        <description>Text that will prepend each outputted XML document's
        file name (default is <tt>Coverage-</tt>).
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>reportfileextension</attribute>
        <description>Text that will append each outputted XML document's
        file name (default is <tt>.xml</tt>).
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-example>
        <source>
&lt;coveragereport
        datadir="${dirs.test-output}/coverage-data"
        logdir="${dirs.test-output}/coverage-log"
        outdir="${dirs.test-output}"&gt;
&lt;/coveragereport&gt;
        </source>
        <description>
        The &lt;coveragereport&gt; task generates one <tt>.xml</tt> file
        for each analysis module that has data in the
        <tt>${dirs.test-output}/coverage-data</tt> directory, using the
        runtime log data found in the <tt>${dirs.test-output}/coverage-log</tt>
        directory.  It also places in the same directory an <tt>.xml</tt> file
        that contains all the analysis module data.
        </description>
    </ant-example>
    <ant-example>
        <source>
&lt;coveragereport
        datadir="${dirs.test-output}/coverage-data"
        logdir="${dirs.test-output}/coverage-log"
        outdir="${dirs.test-output}"&gt;
    &lt;simplestyle destdir="${dirs.test-output}" removeempty="true" /&gt;
    &lt;sourcestyle destdir="${dirs.test-output}/source-report"
        removeempty="true" srcdir="src"
        title="Summary Coverage Report of My Code"&gt;
        
        &lt;srcdir name="${dirs.temp}/generated-source-1" /&gt;
        &lt;srcdir name="${dirs.temp}/generated-source-2" /&gt;
    &lt;/sourcestyle&gt;
&lt;/coveragereport&gt;
        </source>
        <description>
        Same as above, but this also generates two human-readable reports.
        The first (simplestyle) generates one HTML file in the
        <tt>${dirs.test-output}</tt> directory for each analysis module
        XML report.  <special-text>The generated file will
        look something like <link name="CoverageReport-LineCount">this</link>.
        </special-text>
        <p>
        The second (sourcestyle) generates a directory hierarchy of framed
        HTML pages in the <tt>${dirs.test-output}/source-report</tt>
        directory.  It links the original Java source files into the HTML
        by looking in the directories <code>src</code>,
        <code>${dirs.temp}/generated-source-1</code>, and
        <code>${dirs.temp}/generated-source-2</code> for the source files
        corresponding to the covered class files, in that order.
        </p>
        </description>
    </ant-example>
</anttask>

</body>
</document>
