• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<html><head>
2      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
3   <title>Chapter&nbsp;4.&nbsp;Running FindBugs&#8482;</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs&#8482; Manual"><link rel="up" href="index.html" title="FindBugs&#8482; Manual"><link rel="prev" href="building.html" title="Chapter&nbsp;3.&nbsp;Building FindBugs&#8482; from Source"><link rel="next" href="gui.html" title="Chapter&nbsp;5.&nbsp;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&nbsp;4.&nbsp;Running <span class="application">FindBugs</span>&#8482;</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="building.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="gui.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;4.&nbsp;Running FindBugs&#8482;"><div class="titlepage"><div><div><h2 class="title"><a name="running"></a>Chapter&nbsp;4.&nbsp;Running <span class="application">FindBugs</span>&#8482;</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
5command line user interface.  This chapter describes
6how 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.&nbsp;Quick Start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e465"></a>1.&nbsp;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&nbsp;5.&nbsp;Using the FindBugs GUI">Chapter&nbsp;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.&nbsp;Executing FindBugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e503"></a>2.&nbsp;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.&nbsp;Direct invocation of FindBugs"><div class="titlepage"><div><div><h3 class="title"><a name="directInvocation"></a>2.1.&nbsp;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.&nbsp;Choosing the User Interface"><div class="titlepage"><div><div><h4 class="title"><a name="chooseUI"></a>2.1.1.&nbsp;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.&nbsp;Java Virtual Machine (JVM) arguments"><div class="titlepage"><div><div><h4 class="title"><a name="jvmArgs"></a>2.1.2.&nbsp;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.&nbsp;Invocation of FindBugs using a wrapper script"><div class="titlepage"><div><div><h3 class="title"><a name="wrapperScript"></a>2.2.&nbsp;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>
65On 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>
70On Windows systems, the command to invoke the wrapper script is
71</p><pre class="screen">
72<code class="prompt">C:\My Directory&gt;</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>
75On both Unix-like and Windows systems, you can simply add the <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/bin</code>
76directory to your <code class="filename">PATH</code> environment variable and then invoke
77FindBugs using the <span class="command"><strong>findbugs</strong></span> command.
78</p><div class="sect3" title="2.2.1.&nbsp;Wrapper script command line options"><div class="titlepage"><div><div><h4 class="title"><a name="wrapperOptions"></a>2.2.1.&nbsp;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.&nbsp; <span class="application">FindBugs</span> uses system properties
99      to configure analysis options.  See <a class="xref" href="analysisprops.html" title="Chapter&nbsp;9.&nbsp;Analysis Properties">Chapter&nbsp;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.&nbsp;Command-line Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="commandLineOptions"></a>3.&nbsp;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.&nbsp;Common command-line options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e796"></a>3.1.&nbsp;Common command-line options</h3></div></div></div><p>
108These 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.&nbsp;GUI Options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e836"></a>3.2.&nbsp;GUI Options</h3></div></div></div><p>
122These 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.&nbsp;Text UI Options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e852"></a>3.3.&nbsp;Text UI Options</h3></div></div></div><p>
128These 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&nbsp;8.&nbsp;Filter Files">Chapter&nbsp;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&nbsp;8.&nbsp;Filter Files">Chapter&nbsp;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>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="gui.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;3.&nbsp;Building <span class="application">FindBugs</span>&#8482; from Source&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;5.&nbsp;Using the <span class="application">FindBugs</span> GUI</td></tr></table></div></body></html>