<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 6. Using the FindBugs™ Ant task</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="gui.html" title="Chapter 5. Using the FindBugs GUI"><link rel="next" href="eclipse.html" title="Chapter 7. Using the FindBugs™ Eclipse plugin"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Using the <span class="application">FindBugs</span>™ <span class="application">Ant</span> task</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="gui.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="eclipse.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 6. Using the FindBugs™ Ant task"><div class="titlepage"><div><div><h2 class="title"><a name="anttask"></a>Chapter 6. Using the <span class="application">FindBugs</span>™ <span class="application">Ant</span> task</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="anttask.html#d0e1205">1. Installing the <span class="application">Ant</span> task</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1243">2. Modifying build.xml</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1314">3. Executing the task</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1339">4. Parameters</a></span></dt></dl></div><p>
This chapter describes how to integrate <span class="application">FindBugs</span> into a build script
for <a class="ulink" href="http://ant.apache.org/" target="_top"><span class="application">Ant</span></a>, which is a popular Java build
and deployment tool. Using the <span class="application">FindBugs</span> <span class="application">Ant</span> task, your build script can
automatically run <span class="application">FindBugs</span> on your Java code.
</p><p>
The <span class="application">Ant</span> task was generously contributed by Mike Fagan.
</p><div class="sect1" title="1. Installing the Ant task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1205"></a>1. Installing the <span class="application">Ant</span> task</h2></div></div></div><p>
To install the <span class="application">Ant</span> task, simply copy <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs-ant.jar</code>
into the <code class="filename">lib</code> subdirectory of your <span class="application">Ant</span> installation.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>It is strongly recommended that you use the <span class="application">Ant</span> task with the version
of <span class="application">FindBugs</span> it was included with. We do not guarantee that the <span class="application">Ant</span> task Jar file
will work with any version of <span class="application">FindBugs</span> other than the one it was included with.</p></td></tr></table></div><p>
</p></div><div class="sect1" title="2. Modifying build.xml"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1243"></a>2. Modifying build.xml</h2></div></div></div><p>
To incorporate <span class="application">FindBugs</span> into <code class="filename">build.xml</code> (the build script
for <span class="application">Ant</span>), you first need to add a task definition. This should appear as follows:
</p><pre class="screen">
<taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/>
</pre><p>
The task definition specifies that when a <code class="literal">findbugs</code> element is
seen in <code class="filename">build.xml</code>, it should use the indicated class to execute the task.
</p><p>
After you have added the task definition, you can define a target
which uses the <code class="literal">findbugs</code> task. Here is an example
which could be added to the <code class="filename">build.xml</code> for the
Apache <a class="ulink" href="http://jakarta.apache.org/bcel/" target="_top">BCEL</a> library.
</p><pre class="screen">
<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>
</pre><p>
The <code class="literal">findbugs</code> element must have the <code class="literal">home</code>
attribute set to the directory in which <span class="application">FindBugs</span> is installed; in other words,
<em class="replaceable"><code>$FINDBUGS_HOME</code></em>. See <a class="xref" href="installing.html" title="Chapter 2. Installing FindBugs™">Chapter 2, <i>Installing <span class="application">FindBugs</span>™</i></a>.
</p><p>
This target will execute <span class="application">FindBugs</span> on <code class="filename">bcel.jar</code>, 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 <span class="application">FindBugs</span> on it.)
The output of <span class="application">FindBugs</span> will be saved in XML format to a file called
<code class="filename">bcel-fb.xml</code>.
An auxiliary Jar file, <code class="filename">Regex.jar</code>, 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.
</p></div><div class="sect1" title="3. Executing the task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1314"></a>3. Executing the task</h2></div></div></div><p>
Here is an example of invoking <span class="application">Ant</span> from the command line, using the <code class="literal">findbugs</code>
target defined above.
</p><pre class="screen">
<code class="prompt">[daveho@noir]$</code> <span class="command"><strong>ant findbugs</strong></span>
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
</pre><p>
In this case, because we saved the bug results in an XML file, we can
use the <span class="application">FindBugs</span> GUI to view the results; see <a class="xref" href="running.html" title="Chapter 4. Running FindBugs™">Chapter 4, <i>Running <span class="application">FindBugs</span>™</i></a>.
</p></div><div class="sect1" title="4. Parameters"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1339"></a>4. Parameters</h2></div></div></div><p>This section describes the parameters that may be specified when
using the <span class="application">FindBugs</span> task.
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">class</code></span></dt><dd><p>
A optional nested element specifying which classes to analyze. The <code class="literal">class</code>
element must specify a <code class="literal">location</code> attribute which names the
archive file (jar, zip, etc.), directory, or class file to be analyzed. Multiple <code class="literal">class</code>
elements may be specified as children of a single <code class="literal">findbugs</code> element.
</p><p>In addition to or instead of specifying a <code class="literal">class</code> element,
the <span class="application">FindBugs</span> task can contain one or more <code class="literal">fileset</code> 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.
</p></dd><dt><span class="term"><code class="literal">auxClasspath</code></span></dt><dd><p>
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
<span class="application">Ant</span>'s <code class="literal">classpath</code> element for the Java task.
</p></dd><dt><span class="term"><code class="literal">sourcePath</code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="literal">home</code></span></dt><dd><p>
A required attribute.
It must be set to the name of the directory where <span class="application">FindBugs</span> is installed.
</p></dd><dt><span class="term"><code class="literal">quietErrors</code></span></dt><dd><p>
An optional boolean attribute.
If true, reports of serious analysis errors and missing classes will
be suppressed in the <span class="application">FindBugs</span> output. Default is false.
</p></dd><dt><span class="term"><code class="literal">reportLevel</code></span></dt><dd><p>
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 supressed.
If set to "high", only high confidence bugs are reported.
</p></dd><dt><span class="term"><code class="literal">output</code></span></dt><dd><p>
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 <a class="ulink" href="http://www.gnu.org/software/emacs/" target="_top">Emacs</a> error message format.
If set to "xdocs", output is xdoc XML for use with Apache Maven.
</p></dd><dt><span class="term"><code class="literal">stylesheet</code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="literal">sort</code></span></dt><dd><p>
Optional attribute. If the <code class="literal">output</code> attribute
is set to "text", then the <code class="literal">sort</code> attribute specifies
whether or not reported bugs are sorted by class. Default is true.
</p></dd><dt><span class="term"><code class="literal">outputFile</code></span></dt><dd><p>
Optional attribute. If specified, names the output file in which the
<span class="application">FindBugs</span> output will be saved. By default, the output is displayed
directly by <span class="application">Ant</span>.
</p></dd><dt><span class="term"><code class="literal">debug</code></span></dt><dd><p>
Optional boolean attribute. If set to true, <span class="application">FindBugs</span> prints diagnostic
information about which classes are being analyzed, and which bug pattern
detectors are being run. Default is false.
</p></dd><dt><span class="term"><code class="literal">effort</code></span></dt><dd><p>
Set the analysis effort level. The value specified should be
one of <code class="literal">min</code>, <code class="literal">default</code>,
or <code class="literal">max</code>. See <a class="xref" href="running.html#commandLineOptions" title="3. Command-line Options">Section 3, “Command-line Options”</a>
for more information about setting the analysis level.
</p></dd><dt><span class="term"><code class="literal">conserveSpace</code></span></dt><dd><p>Synonym for effort="min".</p></dd><dt><span class="term"><code class="literal">workHard</code></span></dt><dd><p>Synonym for effort="max".</p></dd><dt><span class="term"><code class="literal">visitors</code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="literal">omitVisitors</code></span></dt><dd><p>
Optional attribute. It is like the <code class="literal">visitors</code> attribute,
except it specifies detectors which will <span class="emphasis"><em>not</em></span> be run.
</p></dd><dt><span class="term"><code class="literal">excludeFilter</code></span></dt><dd><p>
Optional attribute. It specifies the filename of a filter specifying bugs
to exclude from being reported. See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>.
</p></dd><dt><span class="term"><code class="literal">includeFilter</code></span></dt><dd><p>
Optional attribute. It specifies the filename of a filter specifying
which bugs are reported. See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>.
</p></dd><dt><span class="term"><code class="literal">projectFile</code></span></dt><dd><p>
Optional attribute. It specifies the name of a project file.
Project files are created by the <span class="application">FindBugs</span> GUI, and specify classes,
aux classpath entries, and source directories. By naming a project,
you don't need to specify any <code class="literal">class</code> elements,
nor do you need to specify <code class="literal">auxClasspath</code> or
<code class="literal">sourcePath</code> attributes.
See <a class="xref" href="running.html" title="Chapter 4. Running FindBugs™">Chapter 4, <i>Running <span class="application">FindBugs</span>™</i></a> for how to create a project.
</p></dd><dt><span class="term"><code class="literal">jvmargs</code></span></dt><dd><p>
Optional attribute. It specifies any arguments that should be passed
to the Java virtual machine used to run <span class="application">FindBugs</span>. 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.
</p></dd><dt><span class="term"><code class="literal">systemProperty</code></span></dt><dd><p>
Optional nested element. If specified, defines a system property.
The <code class="literal">name</code> attribute specifies the name of the
system property, and the <code class="literal">value</code> attribute specifies
the value of the system property.
</p></dd><dt><span class="term"><code class="literal">timeout</code></span></dt><dd><p>
Optional attribute. It specifies the amount of time, in milliseconds,
that the Java process executing <span class="application">FindBugs</span> 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, <span class="application">FindBugs</span> may require more than ten minutes to complete its
analysis.
</p></dd><dt><span class="term"><code class="literal">failOnError</code></span></dt><dd><p>
Optional boolean attribute. Whether to abort the build process if there is an
error running <span class="application">FindBugs</span>. Defaults to "false"
</p></dd><dt><span class="term"><code class="literal">errorProperty</code></span></dt><dd><p>
Optional attribute which specifies the name of a property that
will be set to "true" if an error occurs while running <span class="application">FindBugs</span>.
</p></dd><dt><span class="term"><code class="literal">warningsProperty</code></span></dt><dd><p>
Optional attribute which specifies the name of a property
that will be set to "true" if any warnings are reported by
<span class="application">FindBugs</span> on the analyzed program.
</p></dd><dt><span class="term"><code class="literal">userPreferencesFile</code></span></dt><dd><p>
Optional attribute. Set the path of the user preferences file to use, which might override some of the options abobe.
Specifying <code class="literal">userPreferencesFile</code> 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 FindBugs Eclipse project settings for command
line execution.
</p></dd></dl></div><p>
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gui.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="eclipse.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Using the <span class="application">FindBugs</span> GUI </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Using the <span class="application">FindBugs</span>™ Eclipse plugin</td></tr></table></div></body></html>