This chapter describes how to integrate FindBugs into a build script for Ant, which is a popular Java build and deployment tool. Using the FindBugs Ant task, your build script can automatically run FindBugs on your Java code.
The Ant task was generously contributed by Mike Fagan.
To install the Ant task, simply copy $FINDBUGS_HOME/lib/findbugs-ant.jarlib subdirectory of your Ant installation.
![[Note]](note.png) | Note |
|---|---|
It is strongly recommended that you use the Ant task with the version of FindBugs it was included with. We do not guarantee that the Ant task Jar file will work with any version of FindBugs other than the one it was included with. |
To incorporate FindBugs into build.xml (the build script
for Ant), you first need to add a task definition. This should appear as follows:
<taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/>
The task definition specifies that when a findbugs 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 findbugs task. Here is an example
which could be added to the build.xml for the
Apache BCEL library.
<property name="findbugs.home" value="/export/home/daveho/work/findbugs" />
<target name="findbugs" depends="jar">
<findbugs home="${findbugs.home}"
output="xml"
outputFile="bcel-fb.xml" >
<auxClasspath path="${basedir}/lib/Regex.jar" />
<sourcePath path="${basedir}/src/java" />
<class location="${basedir}/bin/bcel.jar" />
</findbugs>
</target>
The findbugs element must have the home
attribute set to the directory in which FindBugs is installed; in other words,
$FINDBUGS_HOME. See Chapter 2, Installing FindBugs™.
This target will execute FindBugs 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 FindBugs on it.)
The output of FindBugs will be saved in XML format to a file called
bcel-fb.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.
Here is an example of invoking Ant from the command line, using the findbugs
target defined above.
[daveho@noir]$ ant findbugs
Buildfile: build.xml
init:
compile:
examples:
jar:
findbugs:
[findbugs] Running FindBugs...
[findbugs] Bugs were found
[findbugs] Output saved to bcel-fb.xml
BUILD SUCCESSFUL
Total time: 35 seconds
In this case, because we saved the bug results in an XML file, we can use the FindBugs GUI to view the results; see Chapter 4, Running FindBugs™.
This section describes the parameters that may be specified when using the FindBugs task.
classA optional nested element specifying which classes to analyze. The
classelement must specify alocationattribute which names the archive file (jar, zip, etc.), directory, or class file to be analyzed. Multipleclasselements may be specified as children of a singlefindbugselement.In addition to or instead of specifying a
classelement, the FindBugs task can contain one or morefilesetelement(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.auxClasspathAn 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
classpathelement for the Java task.sourcePathAn 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.
homeA required attribute. It must be set to the name of the directory where FindBugs is installed.
quietErrorsAn optional boolean attribute. If true, reports of serious analysis errors and missing classes will be suppressed in the FindBugs output. Default is false.
reportLevelAn 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 supressed. If set to "high", only high confidence bugs are reported.
outputOptional 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.
stylesheetOptional 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.
sortOptional attribute. If the
outputattribute is set to "text", then thesortattribute specifies whether or not reported bugs are sorted by class. Default is true.outputFileOptional attribute. If specified, names the output file in which the FindBugs output will be saved. By default, the output is displayed directly by Ant.
debugOptional boolean attribute. If set to true, FindBugs prints diagnostic information about which classes are being analyzed, and which bug pattern detectors are being run. Default is false.
effortSet the analysis effort level. The value specified should be one of
min,default, ormax. See Section 3, “Command-line Options” for more information about setting the analysis level.conserveSpaceSynonym for effort="min".
workHardSynonym for effort="max".
visitorsOptional 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.
omitVisitorsOptional attribute. It is like the
visitorsattribute, except it specifies detectors which will not be run.excludeFilterOptional attribute. It specifies the filename of a filter specifying bugs to exclude from being reported. See Chapter 8, Filter Files.
includeFilterOptional attribute. It specifies the filename of a filter specifying which bugs are reported. See Chapter 8, Filter Files.
projectFileOptional 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
classelements, nor do you need to specifyauxClasspathorsourcePathattributes. See Chapter 4, Running FindBugs™ for how to create a project.jvmargsOptional attribute. It specifies any arguments that should be passed to the Java virtual machine used to run FindBugs. 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.
systemPropertyOptional nested element. If specified, defines a system property. The
nameattribute specifies the name of the system property, and thevalueattribute specifies the value of the system property.timeoutOptional attribute. It specifies the amount of time, in milliseconds, that the Java process executing FindBugs 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, FindBugs may require more than ten minutes to complete its analysis.
failOnErrorOptional boolean attribute. Whether to abort the build process if there is an error running FindBugs. Defaults to "false"
errorPropertyOptional attribute which specifies the name of a property that will be set to "true" if an error occurs while running FindBugs.
warningsPropertyOptional attribute which specifies the name of a property that will be set to "true" if any warnings are reported by FindBugs on the analyzed program.
userPreferencesFileOptional attribute. Set the path of the user preferences file to use, which might override some of the options abobe. Specifying
userPreferencesFileas 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 FindBugs Eclipse project settings for command line execution.