This chapter describes how to integrate SpotBugs into a build script for Ant, which is a popular Java build and deployment tool. Using the SpotBugs Ant task, your build script can automatically run SpotBugs on your Java code.

The Ant task was generously contributed by Mike Fagan.

Installing the Ant task

To install the Ant task, simply copy $SPOTBUGS_HOME/lib/spotbugs-ant.jar into the lib subdirectory of your Ant installation.

It is strongly recommended that you use the Ant task with the version of SpotBugs it was included with. We do not guarantee that the Ant task Jar file will work with any version of SpotBugs other than the one it was included with.

Modifying build.xml

To incorporate SpotBugs into build.xml (the build script for Ant), you first need to add a task definition. This should appear as follows:

<taskdef
    resource="edu/umd/cs/findbugs/anttask/tasks.properties"
    classpath="path/to/spotbugs-ant.jar" />

The task definition specifies that when a spotbugs element is seen in build.xml, it should use the indicated class to execute the task.

After you have added the task definition, you can define a target which uses the spotbugs task. Here is an example which could be added to the build.xml for the Apache BCEL library.

<property name="spotbugs.home" value="/export/home/daveho/work/spotbugs" />
<target name="spotbugs" depends="jar">
  <spotbugs home="${spotbugs.home}"
            output="xml"
            outputFile="bcel-sb.xml" >
    <auxClasspath path="${basedir}/lib/Regex.jar" />
    <sourcePath path="${basedir}/src/java" />
    <class location="${basedir}/bin/bcel.jar" />
  </spotbugs>
</target>

The spotbugs element must have the home attribute set to the directory in which SpotBugs is installed; in other words, $SPOTBUGS_HOME. See Installing.

This target will execute SpotBugs on bcel.jar, which is the Jar file produced by BCEL’s build script. (By making it depend on the “jar” target, we ensure that the library is fully compiled before running SpotBugs on it.) The output of SpotBugs will be saved in XML format to a file called bcel-sb.xml. An auxiliary Jar file, Regex.jar, is added to the aux classpath, because it is referenced by the main BCEL library. A source path is specified so that the saved bug data will have accurate references to the BCEL source code.

Executing the task

Here is an example of invoking Ant from the command line, using the spotbugs target defined above.

[daveho@noir]$ ant spotbugs
Buildfile: build.xml
init:
compile:
examples:
jar:
spotbugs:
 [spotbugs] Running SpotBugs...
 [spotbugs] Bugs were found
 [spotbugs] Output saved to bcel-sb.xml
BUILD SUCCESSFUL
Total time: 35 seconds

In this case, because we saved the bug results in an XML file, we can use the SpotBugs GUI to view the results; see Running SpotBugs.

Parameters

This section describes the parameters that may be specified when using the FindBugs task.

class

A optional nested element specifying which classes to analyze. The class element must specify a location attribute which names the archive file (jar, zip, etc.), directory, or class file to be analyzed. Multiple class elements may be specified as children of a single spotbugs element.

In addition to or instead of specifying a class element, the SpotBugs task can contain one or more fileset element(s) that specify files to be analyzed. For example, you might use a fileset to specify that all of the jar files in a directory should be analyzed.

auxClasspath

An optional nested element which specifies a classpath (Jar files or directories) containing classes used by the analyzed library or application, but which you don’t want to analyze. It is specified the same way as Ant’s classpath element for the Java task.

sourcePath

An optional nested element which specifies a source directory path containing source files used to compile the Java code being analyzed. By specifying a source path, any generated XML bug output will have complete source information, which allows later viewing in the GUI.

home

A required attribute. It must be set to the name of the directory where SpotBugs is installed.

quietErrors

An optional boolean attribute. If true, reports of serious analysis errors and missing classes will be suppressed in the SpotBugs output. Default is false.

reportLevel

An optional attribute. It specifies the confidence/priority threshold for reporting issues. If set to low, confidence is not used to filter bugs. If set to medium (the default), low confidence issues are suppressed. If set to high, only high confidence bugs are reported.

output

Optional attribute. It specifies the output format. If set to xml (the default), output is in XML format. If set to “xml:withMessages”, output is in XML format augmented with human-readable messages. (You should use this format if you plan to generate a report using an XSL stylesheet.) If set to “html”, output is in HTML formatted (default stylesheet is default.xsl). If set to text, output is in ad-hoc text format. If set to emacs, output is in Emacs error message format. If set to xdocs, output is xdoc XML for use with Apache Maven.

stylesheet

Optional attribute. It specifies the stylesheet to use to generate html output when the output is set to html. Stylesheets included in the FindBugs distribution include default.xsl, fancy.xsl, fancy-hist.xsl, plain.xsl, and summary.xsl. The default value, if no stylesheet attribute is provided, is default.xsl.

sort

Optional attribute. If the output attribute is set to text, then the sort attribute specifies whether or not reported bugs are sorted by class. Default is true.

outputFile

Optional attribute. If specified, names the output file in which the FindBugs output will be saved. By default, the output is displayed directly by Ant.

debug

Optional boolean attribute. If set to true, SpotBugs prints diagnostic information about which classes are being analyzed, and which bug pattern detectors are being run. Default is false.

effort

Set the analysis effort level. The value specified should be one of min, default, or max. See Command-line Options : for more information about setting the analysis level.

conserveSpace

Synonym for effort="min".

workHard

Synonym for effort="max".

visitors

Optional attribute. It specifies a comma-separated list of bug detectors which should be run. The bug detectors are specified by their class names, without any package qualification. By default, all detectors which are not disabled by default are run.

omitVisitors

Optional attribute. It specifies a comma-separated list of bug detectors. It is like the visitors attribute, except it specifies detectors which will not be run.

chooseVisitors

Optional attribute. It specifies a comma-separated list of bug detectors prefixed with “+” or “-” to selectively enable/disable them.

excludeFilter

Optional attribute. It specifies the filename of a filter specifying bugs to exclude from being reported. See Filter file.

excludePath

An optional nested element. It specifies a path containing filters specifying bugs to exclude from being reported. See Filter file.

includeFilter

Optional attribute. It specifies the filename of a filter specifying which bugs are reported. See Filter file.

includePath

An optional nested element. It specifies a path containing filters specifying which bugs are reported. See Filter file.

projectFile

Optional attribute. It specifies the name of a project file. Project files are created by the FindBugs GUI, and specify classes, aux classpath entries, and source directories. By naming a project, you don’t need to specify any class elements, nor do you need to specify auxClasspath or sourcePath attributes. See Running SpotBugs for how to create a project.

jvmargs

Optional attribute. It specifies any arguments that should be passed to the Java virtual machine used to run SpotBugs. You may need to use this attribute to specify flags to increase the amount of memory the JVM may use if you are analyzing a very large program.

systemProperty

Optional nested element. If specified, defines a system property. The name attribute specifies the name of the system property, and the value attribute specifies the value of the system property.

timeout

Optional attribute. It specifies the amount of time, in milliseconds, that the Java process executing SpotBugs may run before it is assumed to be hung and is terminated. The default is 600,000 milliseconds, which is ten minutes. Note that for very large programs, SpotBugs may require more than ten minutes to complete its analysis.

failOnError

Optional boolean attribute. Whether to abort the build process if there is an error running SpotBugs. Defaults to false.

errorProperty

Optional attribute which specifies the name of a property that will be set to true if an error occurs while running SpotBugs.

warningsProperty

Optional attribute which specifies the name of a property that will be set to true if any warnings are reported by SpotBugs on the analyzed program.

userPreferencesFile

Optional attribute. Set the path of the user preferences file to use, which might override some of the options above. Specifying userPreferencesFile as first argument would mean some later options will override them, as last argument would mean they will override some previous options). This rationale behind this option is to reuse SpotBugs Eclipse project settings for command line execution.

nested

Optional attribute which enables or disables scanning of nested jar and zip files found in the list of files and directories to be analyzed. By default, scanning of nested jar/zip files is enabled.

setExitCode

Optional boolean attribute. Whether the exit code will be returned to the main ant job. Defaults to true.