grobo-instrument: GroboCoverage Ant Tasks

Author:Matt Albrecht

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.

Nested Elements

fileset

the FileSet 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.

measure

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.

Parameters

Attribute	Description	Required
`name`	the name of the analysis module to load. The only current acceptable values are: linecount: counts the source code line coverage. This requires the line information to be stored in the class file. 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. branch: counts the coverage of each branch by looking at the bytecode branching instructions. call-pair: counts the coverage of each method invocation. function: counts the "function" or "method" entry coverage; when the execution enters a method, that method is marked as covered.	One of `name` (alternatively, `type`) or `classname` must be specified
`type`	an alternative to the `name` attribute.	One of `name` (alternatively, `type`) or `classname` must be specified
`classname`	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.	One of `name` (alternatively, `type`) or `classname` must be specified
`classpathref`	Reference to a classpath to use when looking up `classname`.	No
`loaderRef`	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.	No

Nested Elements

classpath

Measure's classpath attribute is a PATH like structure and can also be set via a nested classpath element.

loggerprop

Adds a property to be used by the logger specified. Currently, this is only needed if you need to set a property outside the logging output dir.

Parameters

Attribute	Description	Required
`key`	The key for the name-value pair.	Yes
`value`	The value for the name-value pair.	One of `value` or `location` must be specified.
`location`	The value for the name-value pair describing a file location; will be translated into an OS-specific file name.	One of `value` or `location` must be specified.

Parameters

Attribute	Description	Required
`destdir`	The name of the directory in which the recompiled class files are saved. This directory should never be confused with the original classes: these classes are slower and "fatter" than the originals.	Yes
`logger`	the kind of logger used during coverage runtime to gather the code coverage metrics. These are the supported types: safe:(default) This is the safest logger, but the slowest (really 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. 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 `cachesize` 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). There's a pending issue with this logger (bug 902884). As such, this isn't a recommended logger. fast: The fastest logger that comes with GroboCoverage. This operates identically to `safe`, 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 `safe` method. 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 `<logfilter type="single">` tag inside the `<grobo-report>` task.	No
`loggerFactory`	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 `logger` if you want to use a different logger.	No
`logDir`	the directory that will contain data relating to the coverage numbers (gathered during this task and during runtime). Must match the report task's `logDir` parameter.	No
`ifExists`	what to do if the task encounters an existing instrumented class file in the `destdir` directory. Possible values include: replace:default replace the old class data files if a new version of the class file is being post-compiled. clean:remove all files in the `destdir` and class file data directory under `logDir` before post-compiling the code. 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.	No

Examples

<grobo-instrument logger="fast"
        destdir="coverage/classes"
        logdir="coverage/logs"
        >
    <measure name="linecount" />
    <fileset dir="${dirs.classes}" />
    <fileset dir="${dirs.classes2}">
        <excludes name="dont/cover/these/*.class" />
    </fileset>
</grobo-instrument>

Recompiles all the classes located in ${dirs.classes} using the linecount analysis module, and recompiles all the classes from ${dirs.classes2} except those in the dont.cover.these package. All the recompiled classes are stored in coverage/classes, and the data used by the code coverage tasks are stored under the coverage/logs directory. The fast logger will be used during runs.

<grobo-instrument logger="cache"
        destdir="coverage/classes"
        logdir="coverage/logs"
        >
    <measure type="bytecode" />
    <measure classname="org.mine.MeasureType"
        classpathref="myclasspath" />
    
    <fileset dir="${dirs.classes}" />
    <loggerprop key="cachesize" value="100" />
</grobo-instrument>

Recompiles all the classes located in ${dirs.classes} using the bytecode analysis module as well as the user-defined org.mine.MeasureType analysis module. Uses the cache logger, setting the "cachesize" logger property to 100.

All Tasks


This space graciously provided by the SourceForge project	Copyright © 2002-2004 GroboUtils Project. All rights reserved.