Tools like PMD, Checkstyle, FindBugs, Emma and Cobertura deliver high quality code analysis features. The jCoderZ report tool, JcReport, reads the XML output of those tools and creates a single report which combines all findings in one file.
The final HTML report renders the source file as HTML pages and shows the findings directly in the lines, as reported by the tools. Coverage information is displayed in a column at the left of the page.
What the report contains
The archived report for the fawkeZ build held 2932 findings across 325 files: 5 errors, 2222 warnings and 705 information notices. The HTML view lets a reader jump from a finding to the exact source line, rather than switching between four separate tool reports.
Usage
The Ant task for JcReport looks complex, but the structure is straightforward. The example below is the shape used by the fawkeZ build. All paths in a real project need to be adapted to that project.
<jcreport name="fawkez"
dest="${base.dir}/build/doc/findings"
wikibase="https://www.jcoderz.org/wiki/"
webrcsbase="https://www.jcoderz.org/fawkez/browser/trunk"
packagebase="org.jcoderz"
projectbase="${base.dir}"
tempfolder="${base.dir}/build/jcreport"
maxheap="128"
debug="false">
<classpath refid="jcreport.classpath" />
<reports>
<report name="fawkez tests" level="test"
sourcepath="${base.dir}/test/java"
classpath="${build.dir}/classes" />
<report name="fawkez production" level="prod"
sourcepath="${base.dir}/src/java"
classpath="${build.dir}/classes" />
</reports>
<tools>
<pmd config="${pmd.rules}" targetjdk="1.4" encoding="Cp1252">
<classpath refid="pmd.classpath" />
</pmd>
<cpd minimumtokens="100">
<classpath refid="pmd.classpath" />
</cpd>
<findbugs config="${findbugs.rules}" maxheap="512" effort="max" warninglevel="low">
<classpath refid="findbugs.classpath" />
</findbugs>
<checkstyle config="${checkstyle.rules}" maxheap="512">
<classpath refid="checkstyle.classpath" />
</checkstyle>
<cobertura datafile="junit.ser">
<classpath refid="cobertura.classpath" />
</cobertura>
</tools>
<filters>
<filter file="${filter.rules}" />
</filters>
</jcreport>The task produces a report XML file, a summary XML file and a set of HTML pages that make the XML browsable.
The jcreport tag
| Attribute | Meaning |
|---|---|
name | Name of the report, for example fawkez. |
dest | Folder where the HTML report is written. |
wikibase | Base URL of the project wiki, used for links from findings. |
webrcsbase | Base URL of the source browser, used for source links. |
webrcssuffix | Suffix appended to source browser URLs, for example a root parameter. |
packagebase | Package prefix of the project, for example org.jcoderz. |
projectbase | Base directory of the project. |
tempfolder | Working folder for intermediate files. |
maxheap | Heap size in megabytes for the report process. |
debug | Debug flag for the report process. |
oldReportFile | Previous report XML file, used to show historical findings. |
cpus | Number of worker threads used to run the tools in parallel. |
The tag has three child elements: reports, tools and filters.
Reports
The reports element contains one or more report elements. Each report defines a set of source files that the analysis tool chain checks. Files are separated by level, which marks findings in the XML report with a level attribute. That attribute can later be used to filter findings from test code, for example.
<report name="production" level="prod"
sourcepath="${base.dir}/src/java"
classpath="${build.dir}/classes" />Tools
All tools share the maxheap attribute. Each tool runs in its own process, because the tools have different heap requirements. All tools also accept a classpath child element. Because the tools are started as separate processes, that classpath must match the one used when launching the tool from the command line.
| Tool | Role | Notable attributes |
|---|---|---|
pmd | Static analysis of Java source. | config, targetjdk, encoding |
cpd | Copy Paste Detector from the PMD project. | minimumtokens |
findbugs | Byte code analysis for bug patterns. | config, effort, warninglevel |
checkstyle | Coding standard checks. | config |
cobertura | Line coverage from a data file. | datafile |
emma | Branch and block coverage. | datafile |
Notes per tool
- PMD. The config attribute points at the rule set. The target JDK defines the language level of the source files, and the encoding defines the source file encoding.
- CPD. The minimum tokens value is the shortest sequence that counts as copied code.
- FindBugs. The config file is an exclude list. In FindBugs all supported checkers are enabled by default, so the exclude list turns off the rules that should not run. The effort attribute controls how hard FindBugs searches, and the warning level selects which priorities are reported.
- Checkstyle. The config attribute points at the Checkstyle configuration file.
- Cobertura. The datafile attribute names the file into which coverage information was written.
- Emma. Only one of Cobertura or Emma can be configured. Emma reports coverage differently: it records whether a branch was executed, not how often a line was touched. Because a line can hold several branches, the report shows the percentage of covered branches on that line.
Filters
The filters element contains any number of filter elements, each pointing at an XSL file that removes findings from the report XML before the HTML pages are rendered.
<filter file="${filter.rules}" />Rule sets and classpath
In fawkeZ the rule set files are declared as Ant properties, one each for PMD, Checkstyle, FindBugs and the filter. The classpath settings for the different tools must match the classpath used when running those tools from the command line.
The project repository holds the current build files. The summary report builds on the output of this tool.
Task definition
<taskdef name="jcreport"
classname="org.jcoderz.phoenix.report.JcReportAntTask">
<classpath refid="jcreport.classpath" />
</taskdef>