<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
    <name>grobo-instrument: GroboCoverage Ant Tasks</name>
    <doc-version>$Date: 2004/04/18 20:11:05 $</doc-version>
    <author>Matt Albrecht</author>
</head>
<body>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

<anttask name="grobo-instrument">
    <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="CoreTypes/fileset.html">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="measure">
        <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>
            Measure'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> (alternatively,
                <code>type</code>) or <code>classname</code> must be
                specified</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>type</attribute>
            <description>an alternative to the <code>name</code> attribute.
            </description>
            <required>One of <code>name</code> (alternatively,
                <code>type</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> (alternatively,
                <code>type</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="loggerprop">
        <description>
        Adds a property to be used by the <code>logger</code> specified.
        Currently, this is only needed if you need to set a property
        outside the logging output dir.
        </description>
        <ant-parameter>
            <attribute>key</attribute>
            <description>The key for the name-value pair.</description>
            <required>Yes</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>value</attribute>
            <description>The value for the name-value pair.</description>
            <required>One of <code>value</code> or <code>location</code>
            must be specified.</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>location</attribute>
            <description>The value for the name-value pair describing
            a file location; will be translated into an OS-specific
            file name.</description>
            <required>One of <code>value</code> or <code>location</code>
            must be specified.</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-parameter>
        <attribute>destdir</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-parameter>
        <attribute>logger</attribute>
        <description>the kind of logger used during coverage runtime to
        gather the code coverage metrics.  These are the supported types:
            <ul>
                <definition term="safe">(default)
                This is the safest logger, but the slowest
                (<i>really</i> slow). 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 very large amount of disk write access.</definition>
                
                <definition term="cache">
                This 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.
                Use the <code>cachesize</code> logging parameter
                to 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>).  As such, this isn't a recommended logger.
                </p>
                </definition>
                
                <definition term="fast">
                The fastest logger that comes with GroboCoverage.
                This operates identically to <code>safe</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.
                Reports from various users indicate that using this logger
                causes a 90x speed-up over the <code>safe</code> method.
                </definition>
                
                <definition term="single">
                (currently still experimental) instead of creating the
                standard log directory structure, this method outputs
                everything to a single file in the log directory.  The
                code still needs some optimization, and may be a bottleneck
                for threaded applications.  Using this logger requires you
                to use the <code>&lt;logfilter type="single"&gt;</code>
                tag inside the <code><link name="v2_antdoc_grobo-report"
                >&lt;grobo-report&gt;</link></code> task.
                </definition>
            </ul>
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>loggerFactory</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.  The logger class must be in the classpath
        of the code covered classes.  Use this instead of
        <code>logger</code> if you want to use a different logger.
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>logDir</attribute>
        <description>the directory that will contain data relating to the
        coverage numbers (gathered during this task and during
        runtime). Must match the report task's
        <code>logDir</code> parameter.
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>ifExists</attribute>
        <description>what to do if the task encounters an existing
        instrumented class file in the <code>destdir</code> directory.
        Possible values include:
            <ul>
                <definition term="replace"><i>default</i> replace the
                old class data files if a new version of the class file
                is being post-compiled.
                </definition>
                <definition term="clean">remove all files in the
                <code>destdir</code> and class file data directory under
                <code>logDir</code> before post-compiling the code.
                </definition>
                <definition term="keep">keep the original class data
                files, as well as create new ones for the new post-compiled
                class files.  This method can lead to confusion in the
                reports if you're not careful.
                </definition>
            </ul>
        </description>
        <required>No</required>
    </ant-parameter>
    
    <ant-example>
        <source>
&lt;grobo-instrument logger="fast"
        destdir="coverage/classes"
        logdir="coverage/logs"
        &gt;
    &lt;measure 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;/grobo-instrument&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 data used by the code
        coverage tasks are stored under the
        <tt>coverage/logs</tt> directory.  The fast logger will be used
        during runs.
        </description>
    </ant-example>
    
    <ant-example>
        <source>
&lt;grobo-instrument logger="cache"
        destdir="coverage/classes"
        logdir="coverage/logs"
        &gt;
    &lt;measure type="bytecode" /&gt;
    &lt;measure classname="org.mine.MeasureType"
        classpathref="myclasspath" /&gt;
    
    &lt;fileset dir="${dirs.classes}" /&gt;
    &lt;loggerprop key="cachesize" value="100" /&gt;
&lt;/grobo-instrument&gt;
        </source>
        <description>
        Recompiles all the classes located in <tt>${dirs.classes}</tt> using
        the bytecode analysis module as well as the user-defined
        <code>org.mine.MeasureType</code> analysis module.
        Uses the <code>cache</code> logger, setting the "cachesize"
        logger property to 100.
        </description>
    </ant-example>
</anttask>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

</body>
</document>

