1 <html><head> 2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 3 <title>Chapter 4. Running FindBugs™</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="building.html" title="Chapter 3. Building FindBugs™ from Source"><link rel="next" href="gui.html" title="Chapter 5. Using the FindBugs GUI"></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 4. Running <span class="application">FindBugs</span>™</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="building.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="gui.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 4. Running FindBugs™"><div class="titlepage"><div><div><h2 class="title"><a name="running"></a>Chapter 4. Running <span class="application">FindBugs</span>™</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="running.html#d0e465">1. Quick Start</a></span></dt><dt><span class="sect1"><a href="running.html#d0e503">2. Executing <span class="application">FindBugs</span></a></span></dt><dt><span class="sect1"><a href="running.html#commandLineOptions">3. Command-line Options</a></span></dt></dl></div><p> 4 <span class="application">FindBugs</span> has two user interfaces: a graphical user interface (GUI) and a 5 command line user interface. This chapter describes 6 how to run each of these user interfaces. 7 </p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p> 8 This chapter is in the process of being re-written. 9 The rewrite is not complete yet. 10 </p></td></tr></table></div><div class="sect1" title="1. Quick Start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e465"></a>1. Quick Start</h2></div></div></div><p> 11 If you are running <span class="application">FindBugs</span> on a Windows system, 12 double-click on the file <code class="filename"><em class="replaceable"><code>%FINDBUGS_HOME%</code></em>\lib\findbugs.jar</code> to start the <span class="application">FindBugs</span> GUI. 13 </p><p> 14 On a Unix, Linux, or Mac OS X system, run the <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/bin/findbugs</code> 15 script, or run the command </p><pre class="screen"> 16 <span class="command"><strong>java -jar <em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar</strong></span></pre><p> 17 to run the <span class="application">FindBugs</span> GUI. 18 </p><p> 19 Refer to <a class="xref" href="gui.html" title="Chapter 5. Using the FindBugs GUI">Chapter 5, <i>Using the <span class="application">FindBugs</span> GUI</i></a> for information on how to use the GUI. 20 </p></div><div class="sect1" title="2. Executing FindBugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e503"></a>2. Executing <span class="application">FindBugs</span></h2></div></div></div><p> 21 This section describes how to invoke the <span class="application">FindBugs</span> program. 22 There are two ways to invoke <span class="application">FindBugs</span>: directly, or using a 23 wrapper script. 24 </p><div class="sect2" title="2.1. Direct invocation of FindBugs"><div class="titlepage"><div><div><h3 class="title"><a name="directInvocation"></a>2.1. Direct invocation of <span class="application">FindBugs</span></h3></div></div></div><p> 25 The preferred method of running <span class="application">FindBugs</span> is to directly execute 26 <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar</code> using the <span class="command"><strong>-jar</strong></span> 27 command line switch of the JVM (<span class="command"><strong>java</strong></span>) executable. 28 (Versions of <span class="application">FindBugs</span> prior to 1.3.5 required a wrapper script 29 to invoke <span class="application">FindBugs</span>.) 30 </p><p> 31 The general syntax of invoking <span class="application">FindBugs</span> directly is the following: 32 </p><pre class="screen"> 33 <span class="command"><strong>java <em class="replaceable"><code>[JVM arguments]</code></em> -jar <em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar <em class="replaceable"><code>options...</code></em></strong></span> 34 </pre><p> 35 </p><div class="sect3" title="2.1.1. Choosing the User Interface"><div class="titlepage"><div><div><h4 class="title"><a name="chooseUI"></a>2.1.1. Choosing the User Interface</h4></div></div></div><p> 36 The first command line option chooses the <span class="application">FindBugs</span> user interface to execute. 37 Possible values are: 38 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 39 <span class="command"><strong>-gui</strong></span>: runs the graphical user interface (GUI) 40 </p></li><li class="listitem"><p> 41 <span class="command"><strong>-textui</strong></span>: runs the command line user interface 42 </p></li><li class="listitem"><p> 43 <span class="command"><strong>-version</strong></span>: displays the <span class="application">FindBugs</span> version number 44 </p></li><li class="listitem"><p> 45 <span class="command"><strong>-help</strong></span>: displays help information for the 46 <span class="application">FindBugs</span> command line user interface 47 </p></li><li class="listitem"><p> 48 <span class="command"><strong>-gui1</strong></span>: executes the original (obsolete) 49 <span class="application">FindBugs</span> graphical user interface 50 </p></li></ul></div></div><div class="sect3" title="2.1.2. Java Virtual Machine (JVM) arguments"><div class="titlepage"><div><div><h4 class="title"><a name="jvmArgs"></a>2.1.2. Java Virtual Machine (JVM) arguments</h4></div></div></div><p> 51 Several Java Virtual Machine arguments are useful when invoking 52 <span class="application">FindBugs</span>. 53 </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-Xmx<em class="replaceable"><code>NN</code></em>m</strong></span></span></dt><dd><p> 54 Set the maximum Java heap size to <em class="replaceable"><code>NN</code></em> 55 megabytes. <span class="application">FindBugs</span> generally requires a large amount of 56 memory. For a very large project, using 1500 megabytes 57 is not unusual. 58 </p></dd><dt><span class="term"><span class="command"><strong>-D<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></strong></span></span></dt><dd><p> 59 Set a Java system property. For example, you might use the 60 argument <span class="command"><strong>-Duser.language=ja</strong></span> to display 61 GUI messages in Japanese. 62 </p></dd></dl></div></div></div><div class="sect2" title="2.2. Invocation of FindBugs using a wrapper script"><div class="titlepage"><div><div><h3 class="title"><a name="wrapperScript"></a>2.2. Invocation of <span class="application">FindBugs</span> using a wrapper script</h3></div></div></div><p> 63 Another way to run <span class="application">FindBugs</span> is to use a wrapper script. 64 </p><p> 65 On Unix-like systems, use the following command to invoke the wrapper script: 66 </p><pre class="screen"> 67 <code class="prompt">$ </code><span class="command"><strong><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/bin/findbugs <em class="replaceable"><code>options...</code></em></strong></span> 68 </pre><p> 69 </p><p> 70 On Windows systems, the command to invoke the wrapper script is 71 </p><pre class="screen"> 72 <code class="prompt">C:\My Directory></code><span class="command"><strong><em class="replaceable"><code>%FINDBUGS_HOME%</code></em>\bin\findbugs.bat <em class="replaceable"><code>options...</code></em></strong></span> 73 </pre><p> 74 </p><p> 75 On both Unix-like and Windows systems, you can simply add the <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/bin</code> 76 directory to your <code class="filename">PATH</code> environment variable and then invoke 77 FindBugs using the <span class="command"><strong>findbugs</strong></span> command. 78 </p><div class="sect3" title="2.2.1. Wrapper script command line options"><div class="titlepage"><div><div><h4 class="title"><a name="wrapperOptions"></a>2.2.1. Wrapper script command line options</h4></div></div></div><p>The <span class="application">FindBugs</span> wrapper scripts support the following command-line options. 79 Note that these command line options are <span class="emphasis"><em>not</em></span> handled by 80 the <span class="application">FindBugs</span> program per se; rather, they are handled by the wrapper 81 script. 82 </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-jvmArgs <em class="replaceable"><code>args</code></em></strong></span></span></dt><dd><p> 83 Specifies arguments to pass to the JVM. For example, you might want 84 to set a JVM property: 85 </p><pre class="screen"> 86 <code class="prompt">$ </code><span class="command"><strong>findbugs -textui -jvmArgs "-Duser.language=ja" <em class="replaceable"><code>myApp.jar</code></em></strong></span> 87 </pre><p> 88 </p></dd><dt><span class="term"><span class="command"><strong>-javahome <em class="replaceable"><code>directory</code></em></strong></span></span></dt><dd><p> 89 Specifies the directory containing the JRE (Java Runtime Environment) to 90 use to execute <span class="application">FindBugs</span>. 91 </p></dd><dt><span class="term"><span class="command"><strong>-maxHeap <em class="replaceable"><code>size</code></em></strong></span></span></dt><dd><p> 92 Specifies the maximum Java heap size in megabytes. The default is 256. 93 More memory may be required to analyze very large programs or libraries. 94 </p></dd><dt><span class="term"><span class="command"><strong>-debug</strong></span></span></dt><dd><p> 95 Prints a trace of detectors run and classes analyzed to standard output. 96 Useful for troubleshooting unexpected analysis failures. 97 </p></dd><dt><span class="term"><span class="command"><strong>-property</strong></span> <em class="replaceable"><code>name=value</code></em></span></dt><dd><p> 98 This option sets a system property. <span class="application">FindBugs</span> uses system properties 99 to configure analysis options. See <a class="xref" href="analysisprops.html" title="Chapter 9. Analysis Properties">Chapter 9, <i>Analysis Properties</i></a>. 100 You can use this option multiple times in order to set multiple properties. 101 Note: In most versions of Windows, the <em class="replaceable"><code>name=value</code></em> 102 string must be in quotes. 103 </p></dd></dl></div></div></div></div><div class="sect1" title="3. Command-line Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="commandLineOptions"></a>3. Command-line Options</h2></div></div></div><p> 104 This section describes the command line options supported by <span class="application">FindBugs</span>. 105 These command line options may be used when invoking <span class="application">FindBugs</span> directly, 106 or when using a wrapper script. 107 </p><div class="sect2" title="3.1. Common command-line options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e796"></a>3.1. Common command-line options</h3></div></div></div><p> 108 These options may be used with both the GUI and command-line interfaces. 109 </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-effort:min</strong></span></span></dt><dd><p> 110 This option disables analyses that increase precision but also 111 increase memory consumption. You may want to try this option if 112 you find that <span class="application">FindBugs</span> runs out of memory, or takes an unusually 113 long time to complete its analysis. 114 </p></dd><dt><span class="term"><span class="command"><strong>-effort:max</strong></span></span></dt><dd><p> 115 Enable analyses which increase precision and find more bugs, but which 116 may require more memory and take more time to complete. 117 </p></dd><dt><span class="term"><span class="command"><strong>-project</strong></span> <em class="replaceable"><code>project</code></em></span></dt><dd><p> 118 Specify a project to be analyzed. The project file you specify should 119 be one that was created using the GUI interface. It will typically end 120 in the extension <code class="filename">.fb</code> or <code class="filename">.fbp</code>. 121 </p></dd></dl></div></div><div class="sect2" title="3.2. GUI Options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e836"></a>3.2. GUI Options</h3></div></div></div><p> 122 These options are only accepted by the Graphical User Interface. 123 124 </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-look:</strong></span><em class="replaceable"><code>plastic|gtk|native</code></em></span></dt><dd><p> 125 Set Swing look and feel. 126 </p></dd></dl></div><p> 127 </p></div><div class="sect2" title="3.3. Text UI Options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e852"></a>3.3. Text UI Options</h3></div></div></div><p> 128 These options are only accepted by the Text User Interface. 129 </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-sortByClass</strong></span></span></dt><dd><p> 130 Sort reported bug instances by class name. 131 </p></dd><dt><span class="term"><span class="command"><strong>-include</strong></span> <em class="replaceable"><code>filterFile.xml</code></em></span></dt><dd><p> 132 Only report bug instances that match the filter specified by <em class="replaceable"><code>filterFile.xml</code></em>. 133 See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. 134 </p></dd><dt><span class="term"><span class="command"><strong>-exclude</strong></span> <em class="replaceable"><code>filterFile.xml</code></em></span></dt><dd><p> 135 Report all bug instances except those matching the filter specified by <em class="replaceable"><code>filterFile.xml</code></em>. 136 See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. 137 </p></dd><dt><span class="term"><span class="command"><strong>-onlyAnalyze</strong></span> <em class="replaceable"><code>com.foobar.MyClass,com.foobar.mypkg.*</code></em></span></dt><dd><p> 138 Restrict analysis to find bugs to given comma-separated list of 139 classes and packages. 140 Unlike filtering, this option avoids running analysis on 141 classes and packages that are not explicitly matched: 142 for large projects, this may greatly reduce the amount of time 143 needed to run the analysis. (However, some detectors may produce 144 inaccurate results if they aren't run on the entire application.) 145 Classes should be specified using their full classnames (including 146 package), and packages should be specified in the same way 147 they would in a Java <code class="literal">import</code> statement to 148 import all classes in the package (i.e., add <code class="literal">.*</code> 149 to the full name of the package). 150 Replace <code class="literal">.*</code> with <code class="literal">.-</code> to also 151 analyze all subpackages. 152 </p></dd><dt><span class="term"><span class="command"><strong>-low</strong></span></span></dt><dd><p> 153 Report all bugs. 154 </p></dd><dt><span class="term"><span class="command"><strong>-medium</strong></span></span></dt><dd><p> 155 Report medium and high priority bugs. This is the default setting. 156 </p></dd><dt><span class="term"><span class="command"><strong>-high</strong></span></span></dt><dd><p> 157 Report only high priority bugs. 158 </p></dd><dt><span class="term"><span class="command"><strong>-relaxed</strong></span></span></dt><dd><p> 159 Relaxed reporting mode. For many detectors, this option 160 suppresses the heuristics used to avoid reporting false positives. 161 </p></dd><dt><span class="term"><span class="command"><strong>-xml</strong></span></span></dt><dd><p> 162 Produce the bug reports as XML. The XML data produced may be 163 viewed in the GUI at a later time. You may also specify this 164 option as <span class="command"><strong>-xml:withMessages</strong></span>; when this variant 165 of the option is used, the XML output will contain human-readable 166 messages describing the warnings contained in the file. 167 XML files generated this way are easy to transform into reports. 168 </p></dd><dt><span class="term"><span class="command"><strong>-html</strong></span></span></dt><dd><p> 169 Generate HTML output. By default, <span class="application">FindBugs</span> will use the <code class="filename">default.xsl</code> 170 <a class="ulink" href="http://www.w3.org/TR/xslt" target="_top">XSLT</a> 171 stylesheet to generate the HTML: you can find this file in <code class="filename">findbugs.jar</code>, 172 or in the <span class="application">FindBugs</span> source or binary distributions. Variants of this option include 173 <span class="command"><strong>-html:plain.xsl</strong></span>, <span class="command"><strong>-html:fancy.xsl</strong></span> and <span class="command"><strong>-html:fancy-hist.xsl</strong></span>. 174 The <code class="filename">plain.xsl</code> stylesheet does not use Javascript or DOM, 175 and may work better with older web browsers, or for printing. The <code class="filename">fancy.xsl</code> 176 stylesheet uses DOM and Javascript for navigation and CSS for 177 visual presentation. The <span class="command"><strong>fancy-hist.xsl</strong></span> an evolution of <span class="command"><strong>fancy.xsl</strong></span> stylesheet. 178 It makes an extensive use of DOM and Javascript for dynamically filtering the lists of bugs. 179 </p><p> 180 If you want to specify your own 181 XSLT stylesheet to perform the transformation to HTML, specify the option as 182 <span class="command"><strong>-html:<em class="replaceable"><code>myStylesheet.xsl</code></em></strong></span>, 183 where <em class="replaceable"><code>myStylesheet.xsl</code></em> is the filename of the 184 stylesheet you want to use. 185 </p></dd><dt><span class="term"><span class="command"><strong>-emacs</strong></span></span></dt><dd><p> 186 Produce the bug reports in Emacs format. 187 </p></dd><dt><span class="term"><span class="command"><strong>-xdocs</strong></span></span></dt><dd><p> 188 Produce the bug reports in xdoc XML format for use with Apache Maven. 189 </p></dd><dt><span class="term"><span class="command"><strong>-output</strong></span> <em class="replaceable"><code>filename</code></em></span></dt><dd><p> 190 Produce the output in the specified file. 191 </p></dd><dt><span class="term"><span class="command"><strong>-outputFile</strong></span> <em class="replaceable"><code>filename</code></em></span></dt><dd><p> 192 This argument is deprecated. Use <span class="command"><strong>-output</strong></span> instead. 193 </p></dd><dt><span class="term"><span class="command"><strong>-nested</strong></span><em class="replaceable"><code>[:true|false]</code></em></span></dt><dd><p> 194 This option enables or disables scanning of nested jar and zip files found in 195 the list of files and directories to be analyzed. 196 By default, scanning of nested jar/zip files is enabled. 197 To disable it, add <span class="command"><strong>-nested:false</strong></span> to the command line 198 arguments. 199 </p></dd><dt><span class="term"><span class="command"><strong>-auxclasspath</strong></span> <em class="replaceable"><code>classpath</code></em></span></dt><dd><p> 200 Set the auxiliary classpath for analysis. This classpath should include all 201 jar files and directories containing classes that are part of the program 202 being analyzed but you do not want to have analyzed for bugs. 203 </p></dd><dt><span class="term"><span class="command"><strong>-userPrefs</strong></span> <em class="replaceable"><code>edu.umd.cs.findbugs.core.prefs</code></em></span></dt><dd><p> 204 Set the path of the user preferences file to use, which might override some of the options abobe. 205 Specifying <code class="literal">userPrefs</code> as first argument would mean some later 206 options will override them, as last argument would mean they will override some previous options). 207 This rationale behind this option is to reuse FindBugs Eclipse project settings for command 208 line execution. 209 </p></dd></dl></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="building.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="gui.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Building <span class="application">FindBugs</span>™ from Source </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Using the <span class="application">FindBugs</span> GUI</td></tr></table></div></body></html>
