1 <html><head> 2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 3 <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> 4 This chapter describes how to integrate <span class="application">FindBugs</span> into a build script 5 for <a class="ulink" href="http://ant.apache.org/" target="_top"><span class="application">Ant</span></a>, which is a popular Java build 6 and deployment tool. Using the <span class="application">FindBugs</span> <span class="application">Ant</span> task, your build script can 7 automatically run <span class="application">FindBugs</span> on your Java code. 8 </p><p> 9 The <span class="application">Ant</span> task was generously contributed by Mike Fagan. 10 </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> 11 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> 12 into the <code class="filename">lib</code> subdirectory of your <span class="application">Ant</span> installation. 13 14 </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 15 of <span class="application">FindBugs</span> it was included with. We do not guarantee that the <span class="application">Ant</span> task Jar file 16 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> 17 </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> 18 To incorporate <span class="application">FindBugs</span> into <code class="filename">build.xml</code> (the build script 19 for <span class="application">Ant</span>), you first need to add a task definition. This should appear as follows: 20 21 </p><pre class="screen"> 22 <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/> 23 </pre><p> 24 25 The task definition specifies that when a <code class="literal">findbugs</code> element is 26 seen in <code class="filename">build.xml</code>, it should use the indicated class to execute the task. 27 </p><p> 28 After you have added the task definition, you can define a target 29 which uses the <code class="literal">findbugs</code> task. Here is an example 30 which could be added to the <code class="filename">build.xml</code> for the 31 Apache <a class="ulink" href="http://jakarta.apache.org/bcel/" target="_top">BCEL</a> library. 32 33 </p><pre class="screen"> 34 <property name="findbugs.home" value="/export/home/daveho/work/findbugs" /> 35 36 <target name="findbugs" depends="jar"> 37 <findbugs home="${findbugs.home}" 38 output="xml" 39 outputFile="bcel-fb.xml" > 40 <auxClasspath path="${basedir}/lib/Regex.jar" /> 41 <sourcePath path="${basedir}/src/java" /> 42 <class location="${basedir}/bin/bcel.jar" /> 43 </findbugs> 44 </target> 45 </pre><p> 46 47 The <code class="literal">findbugs</code> element must have the <code class="literal">home</code> 48 attribute set to the directory in which <span class="application">FindBugs</span> is installed; in other words, 49 <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>. 50 </p><p> 51 This target will execute <span class="application">FindBugs</span> on <code class="filename">bcel.jar</code>, which is the 52 Jar file produced by BCEL's build script. (By making it depend on the "jar" 53 target, we ensure that the library is fully compiled before running <span class="application">FindBugs</span> on it.) 54 The output of <span class="application">FindBugs</span> will be saved in XML format to a file called 55 <code class="filename">bcel-fb.xml</code>. 56 An auxiliary Jar file, <code class="filename">Regex.jar</code>, is added to the aux classpath, 57 because it is referenced by the main BCEL library. A source path is specified 58 so that the saved bug data will have accurate references to the BCEL source code. 59 </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> 60 Here is an example of invoking <span class="application">Ant</span> from the command line, using the <code class="literal">findbugs</code> 61 target defined above. 62 63 </p><pre class="screen"> 64 <code class="prompt">[daveho@noir]$</code> <span class="command"><strong>ant findbugs</strong></span> 65 Buildfile: build.xml 66 67 init: 68 69 compile: 70 71 examples: 72 73 jar: 74 75 findbugs: 76 [findbugs] Running FindBugs... 77 [findbugs] Bugs were found 78 [findbugs] Output saved to bcel-fb.xml 79 80 BUILD SUCCESSFUL 81 Total time: 35 seconds 82 </pre><p> 83 84 In this case, because we saved the bug results in an XML file, we can 85 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>. 86 </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 87 using the <span class="application">FindBugs</span> task. 88 89 </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">class</code></span></dt><dd><p> 90 A optional nested element specifying which classes to analyze. The <code class="literal">class</code> 91 element must specify a <code class="literal">location</code> attribute which names the 92 archive file (jar, zip, etc.), directory, or class file to be analyzed. Multiple <code class="literal">class</code> 93 elements may be specified as children of a single <code class="literal">findbugs</code> element. 94 </p><p>In addition to or instead of specifying a <code class="literal">class</code> element, 95 the <span class="application">FindBugs</span> task can contain one or more <code class="literal">fileset</code> element(s) that 96 specify files to be analyzed. 97 For example, you might use a fileset to specify that all of the jar files in a directory 98 should be analyzed. 99 </p></dd><dt><span class="term"><code class="literal">auxClasspath</code></span></dt><dd><p> 100 An optional nested element which specifies a classpath (Jar files or directories) 101 containing classes used by the analyzed library or application, but which 102 you don't want to analyze. It is specified the same way as 103 <span class="application">Ant</span>'s <code class="literal">classpath</code> element for the Java task. 104 </p></dd><dt><span class="term"><code class="literal">sourcePath</code></span></dt><dd><p> 105 An optional nested element which specifies a source directory path 106 containing source files used to compile the Java code being analyzed. 107 By specifying a source path, any generated XML bug output will have 108 complete source information, which allows later viewing in the 109 GUI. 110 </p></dd><dt><span class="term"><code class="literal">home</code></span></dt><dd><p> 111 A required attribute. 112 It must be set to the name of the directory where <span class="application">FindBugs</span> is installed. 113 </p></dd><dt><span class="term"><code class="literal">quietErrors</code></span></dt><dd><p> 114 An optional boolean attribute. 115 If true, reports of serious analysis errors and missing classes will 116 be suppressed in the <span class="application">FindBugs</span> output. Default is false. 117 </p></dd><dt><span class="term"><code class="literal">reportLevel</code></span></dt><dd><p> 118 An optional attribute. It specifies 119 the confidence/priority threshold for reporting issues. If set to "low", confidence is not used to filter bugs. 120 If set to "medium" (the default), low confidence issues are supressed. 121 If set to "high", only high confidence bugs are reported. 122 </p></dd><dt><span class="term"><code class="literal">output</code></span></dt><dd><p> 123 Optional attribute. 124 It specifies the output format. If set to "xml" (the default), output 125 is in XML format. 126 If set to "xml:withMessages", output is in XML format augmented with 127 human-readable messages. (You should use this format if you plan 128 to generate a report using an XSL stylesheet.) 129 If set to "html", output is in HTML formatted (default stylesheet is default.xsl). 130 If set to "text", output is in ad-hoc text format. 131 If set to "emacs", output is in <a class="ulink" href="http://www.gnu.org/software/emacs/" target="_top">Emacs</a> error message format. 132 If set to "xdocs", output is xdoc XML for use with Apache Maven. 133 </p></dd><dt><span class="term"><code class="literal">stylesheet</code></span></dt><dd><p> 134 Optional attribute. 135 It specifies the stylesheet to use to generate html output when the output is set to html. 136 Stylesheets included in the FindBugs distribution include default.xsl, fancy.xsl, fancy-hist.xsl, plain.xsl, and summary.xsl. 137 The default value, if no stylesheet attribute is provided, is default.xsl. 138 139 </p></dd><dt><span class="term"><code class="literal">sort</code></span></dt><dd><p> 140 Optional attribute. If the <code class="literal">output</code> attribute 141 is set to "text", then the <code class="literal">sort</code> attribute specifies 142 whether or not reported bugs are sorted by class. Default is true. 143 </p></dd><dt><span class="term"><code class="literal">outputFile</code></span></dt><dd><p> 144 Optional attribute. If specified, names the output file in which the 145 <span class="application">FindBugs</span> output will be saved. By default, the output is displayed 146 directly by <span class="application">Ant</span>. 147 </p></dd><dt><span class="term"><code class="literal">debug</code></span></dt><dd><p> 148 Optional boolean attribute. If set to true, <span class="application">FindBugs</span> prints diagnostic 149 information about which classes are being analyzed, and which bug pattern 150 detectors are being run. Default is false. 151 </p></dd><dt><span class="term"><code class="literal">effort</code></span></dt><dd><p> 152 Set the analysis effort level. The value specified should be 153 one of <code class="literal">min</code>, <code class="literal">default</code>, 154 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> 155 for more information about setting the analysis level. 156 </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> 157 Optional attribute. It specifies a comma-separated list of bug detectors 158 which should be run. The bug detectors are specified by their class names, 159 without any package qualification. By default, all detectors which are 160 not disabled by default are run. 161 </p></dd><dt><span class="term"><code class="literal">omitVisitors</code></span></dt><dd><p> 162 Optional attribute. It is like the <code class="literal">visitors</code> attribute, 163 except it specifies detectors which will <span class="emphasis"><em>not</em></span> be run. 164 </p></dd><dt><span class="term"><code class="literal">excludeFilter</code></span></dt><dd><p> 165 Optional attribute. It specifies the filename of a filter specifying bugs 166 to exclude from being reported. See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. 167 </p></dd><dt><span class="term"><code class="literal">includeFilter</code></span></dt><dd><p> 168 Optional attribute. It specifies the filename of a filter specifying 169 which bugs are reported. See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. 170 </p></dd><dt><span class="term"><code class="literal">projectFile</code></span></dt><dd><p> 171 Optional attribute. It specifies the name of a project file. 172 Project files are created by the <span class="application">FindBugs</span> GUI, and specify classes, 173 aux classpath entries, and source directories. By naming a project, 174 you don't need to specify any <code class="literal">class</code> elements, 175 nor do you need to specify <code class="literal">auxClasspath</code> or 176 <code class="literal">sourcePath</code> attributes. 177 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. 178 </p></dd><dt><span class="term"><code class="literal">jvmargs</code></span></dt><dd><p> 179 Optional attribute. It specifies any arguments that should be passed 180 to the Java virtual machine used to run <span class="application">FindBugs</span>. You may need to 181 use this attribute to specify flags to increase the amount of memory 182 the JVM may use if you are analyzing a very large program. 183 </p></dd><dt><span class="term"><code class="literal">systemProperty</code></span></dt><dd><p> 184 Optional nested element. If specified, defines a system property. 185 The <code class="literal">name</code> attribute specifies the name of the 186 system property, and the <code class="literal">value</code> attribute specifies 187 the value of the system property. 188 </p></dd><dt><span class="term"><code class="literal">timeout</code></span></dt><dd><p> 189 Optional attribute. It specifies the amount of time, in milliseconds, 190 that the Java process executing <span class="application">FindBugs</span> may run before it is 191 assumed to be hung and is terminated. The default is 600,000 192 milliseconds, which is ten minutes. Note that for very large 193 programs, <span class="application">FindBugs</span> may require more than ten minutes to complete its 194 analysis. 195 </p></dd><dt><span class="term"><code class="literal">failOnError</code></span></dt><dd><p> 196 Optional boolean attribute. Whether to abort the build process if there is an 197 error running <span class="application">FindBugs</span>. Defaults to "false" 198 </p></dd><dt><span class="term"><code class="literal">errorProperty</code></span></dt><dd><p> 199 Optional attribute which specifies the name of a property that 200 will be set to "true" if an error occurs while running <span class="application">FindBugs</span>. 201 </p></dd><dt><span class="term"><code class="literal">warningsProperty</code></span></dt><dd><p> 202 Optional attribute which specifies the name of a property 203 that will be set to "true" if any warnings are reported by 204 <span class="application">FindBugs</span> on the analyzed program. 205 </p></dd><dt><span class="term"><code class="literal">userPreferencesFile</code></span></dt><dd><p> 206 Optional attribute. Set the path of the user preferences file to use, which might override some of the options abobe. 207 Specifying <code class="literal">userPreferencesFile</code> as first argument would mean some later 208 options will override them, as last argument would mean they will override some previous options). 209 This rationale behind this option is to reuse FindBugs Eclipse project settings for command 210 line execution. 211 </p></dd></dl></div><p> 212 213 214 </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>
