<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<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>
<span class="application">FindBugs</span> has two user interfaces: a graphical user interface (GUI) and a
command line user interface. This chapter describes
how to run each of these user interfaces.
</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>
This chapter is in the process of being re-written.
The rewrite is not complete yet.
</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>
If you are running <span class="application">FindBugs</span> on a Windows system,
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.
</p><p>
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>
script, or run the command </p><pre class="screen">
<span class="command"><strong>java -jar <em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar</strong></span></pre><p>
to run the <span class="application">FindBugs</span> GUI.
</p><p>
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.
</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>
This section describes how to invoke the <span class="application">FindBugs</span> program.
There are two ways to invoke <span class="application">FindBugs</span>: directly, or using a
wrapper script.
</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>
The preferred method of running <span class="application">FindBugs</span> is to directly execute
<code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar</code> using the <span class="command"><strong>-jar</strong></span>
command line switch of the JVM (<span class="command"><strong>java</strong></span>) executable.
(Versions of <span class="application">FindBugs</span> prior to 1.3.5 required a wrapper script
to invoke <span class="application">FindBugs</span>.)
</p><p>
The general syntax of invoking <span class="application">FindBugs</span> directly is the following:
</p><pre class="screen">
<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>
</pre><p>
</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>
The first command line option chooses the <span class="application">FindBugs</span> user interface to execute.
Possible values are:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<span class="command"><strong>-gui</strong></span>: runs the graphical user interface (GUI)
</p></li><li class="listitem"><p>
<span class="command"><strong>-textui</strong></span>: runs the command line user interface
</p></li><li class="listitem"><p>
<span class="command"><strong>-version</strong></span>: displays the <span class="application">FindBugs</span> version number
</p></li><li class="listitem"><p>
<span class="command"><strong>-help</strong></span>: displays help information for the
<span class="application">FindBugs</span> command line user interface
</p></li><li class="listitem"><p>
<span class="command"><strong>-gui1</strong></span>: executes the original (obsolete)
<span class="application">FindBugs</span> graphical user interface
</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>
Several Java Virtual Machine arguments are useful when invoking
<span class="application">FindBugs</span>.
</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>
Set the maximum Java heap size to <em class="replaceable"><code>NN</code></em>
megabytes. <span class="application">FindBugs</span> generally requires a large amount of
memory. For a very large project, using 1500 megabytes
is not unusual.
</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>
Set a Java system property. For example, you might use the
argument <span class="command"><strong>-Duser.language=ja</strong></span> to display
GUI messages in Japanese.
</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>
Another way to run <span class="application">FindBugs</span> is to use a wrapper script.
</p><p>
On Unix-like systems, use the following command to invoke the wrapper script:
</p><pre class="screen">
<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>
</pre><p>
</p><p>
On Windows systems, the command to invoke the wrapper script is
</p><pre class="screen">
<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>
</pre><p>
</p><p>
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>
directory to your <code class="filename">PATH</code> environment variable and then invoke
FindBugs using the <span class="command"><strong>findbugs</strong></span> command.
</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.
Note that these command line options are <span class="emphasis"><em>not</em></span> handled by
the <span class="application">FindBugs</span> program per se; rather, they are handled by the wrapper
script.
</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>
Specifies arguments to pass to the JVM. For example, you might want
to set a JVM property:
</p><pre class="screen">
<code class="prompt">$ </code><span class="command"><strong>findbugs -textui -jvmArgs "-Duser.language=ja" <em class="replaceable"><code>myApp.jar</code></em></strong></span>
</pre><p>
</p></dd><dt><span class="term"><span class="command"><strong>-javahome <em class="replaceable"><code>directory</code></em></strong></span></span></dt><dd><p>
Specifies the directory containing the JRE (Java Runtime Environment) to
use to execute <span class="application">FindBugs</span>.
</p></dd><dt><span class="term"><span class="command"><strong>-maxHeap <em class="replaceable"><code>size</code></em></strong></span></span></dt><dd><p>
Specifies the maximum Java heap size in megabytes. The default is 256.
More memory may be required to analyze very large programs or libraries.
</p></dd><dt><span class="term"><span class="command"><strong>-debug</strong></span></span></dt><dd><p>
Prints a trace of detectors run and classes analyzed to standard output.
Useful for troubleshooting unexpected analysis failures.
</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>
This option sets a system property. <span class="application">FindBugs</span> uses system properties
to configure analysis options. See <a class="xref" href="analysisprops.html" title="Chapter 9. Analysis Properties">Chapter 9, <i>Analysis Properties</i></a>.
You can use this option multiple times in order to set multiple properties.
Note: In most versions of Windows, the <em class="replaceable"><code>name=value</code></em>
string must be in quotes.
</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>
This section describes the command line options supported by <span class="application">FindBugs</span>.
These command line options may be used when invoking <span class="application">FindBugs</span> directly,
or when using a wrapper script.
</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>
These options may be used with both the GUI and command-line interfaces.
</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-effort:min</strong></span></span></dt><dd><p>
This option disables analyses that increase precision but also
increase memory consumption. You may want to try this option if
you find that <span class="application">FindBugs</span> runs out of memory, or takes an unusually
long time to complete its analysis.
</p></dd><dt><span class="term"><span class="command"><strong>-effort:max</strong></span></span></dt><dd><p>
Enable analyses which increase precision and find more bugs, but which
may require more memory and take more time to complete.
</p></dd><dt><span class="term"><span class="command"><strong>-project</strong></span> <em class="replaceable"><code>project</code></em></span></dt><dd><p>
Specify a project to be analyzed. The project file you specify should
be one that was created using the GUI interface. It will typically end
in the extension <code class="filename">.fb</code> or <code class="filename">.fbp</code>.
</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>
These options are only accepted by the Graphical User Interface.
</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>
Set Swing look and feel.
</p></dd></dl></div><p>
</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>
These options are only accepted by the Text User Interface.
</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-sortByClass</strong></span></span></dt><dd><p>
Sort reported bug instances by class name.
</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>
Only report bug instances that match the filter specified by <em class="replaceable"><code>filterFile.xml</code></em>.
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"><span class="command"><strong>-exclude</strong></span> <em class="replaceable"><code>filterFile.xml</code></em></span></dt><dd><p>
Report all bug instances except those matching the filter specified by <em class="replaceable"><code>filterFile.xml</code></em>.
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"><span class="command"><strong>-onlyAnalyze</strong></span> <em class="replaceable"><code>com.foobar.MyClass,com.foobar.mypkg.*</code></em></span></dt><dd><p>
Restrict analysis to find bugs to given comma-separated list of
classes and packages.
Unlike filtering, this option avoids running analysis on
classes and packages that are not explicitly matched:
for large projects, this may greatly reduce the amount of time
needed to run the analysis. (However, some detectors may produce
inaccurate results if they aren't run on the entire application.)
Classes should be specified using their full classnames (including
package), and packages should be specified in the same way
they would in a Java <code class="literal">import</code> statement to
import all classes in the package (i.e., add <code class="literal">.*</code>
to the full name of the package).
Replace <code class="literal">.*</code> with <code class="literal">.-</code> to also
analyze all subpackages.
</p></dd><dt><span class="term"><span class="command"><strong>-low</strong></span></span></dt><dd><p>
Report all bugs.
</p></dd><dt><span class="term"><span class="command"><strong>-medium</strong></span></span></dt><dd><p>
Report medium and high priority bugs. This is the default setting.
</p></dd><dt><span class="term"><span class="command"><strong>-high</strong></span></span></dt><dd><p>
Report only high priority bugs.
</p></dd><dt><span class="term"><span class="command"><strong>-relaxed</strong></span></span></dt><dd><p>
Relaxed reporting mode. For many detectors, this option
suppresses the heuristics used to avoid reporting false positives.
</p></dd><dt><span class="term"><span class="command"><strong>-xml</strong></span></span></dt><dd><p>
Produce the bug reports as XML. The XML data produced may be
viewed in the GUI at a later time. You may also specify this
option as <span class="command"><strong>-xml:withMessages</strong></span>; when this variant
of the option is used, the XML output will contain human-readable
messages describing the warnings contained in the file.
XML files generated this way are easy to transform into reports.
</p></dd><dt><span class="term"><span class="command"><strong>-html</strong></span></span></dt><dd><p>
Generate HTML output. By default, <span class="application">FindBugs</span> will use the <code class="filename">default.xsl</code>
<a class="ulink" href="http://www.w3.org/TR/xslt" target="_top">XSLT</a>
stylesheet to generate the HTML: you can find this file in <code class="filename">findbugs.jar</code>,
or in the <span class="application">FindBugs</span> source or binary distributions. Variants of this option include
<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>.
The <code class="filename">plain.xsl</code> stylesheet does not use Javascript or DOM,
and may work better with older web browsers, or for printing. The <code class="filename">fancy.xsl</code>
stylesheet uses DOM and Javascript for navigation and CSS for
visual presentation. The <span class="command"><strong>fancy-hist.xsl</strong></span> an evolution of <span class="command"><strong>fancy.xsl</strong></span> stylesheet.
It makes an extensive use of DOM and Javascript for dynamically filtering the lists of bugs.
</p><p>
If you want to specify your own
XSLT stylesheet to perform the transformation to HTML, specify the option as
<span class="command"><strong>-html:<em class="replaceable"><code>myStylesheet.xsl</code></em></strong></span>,
where <em class="replaceable"><code>myStylesheet.xsl</code></em> is the filename of the
stylesheet you want to use.
</p></dd><dt><span class="term"><span class="command"><strong>-emacs</strong></span></span></dt><dd><p>
Produce the bug reports in Emacs format.
</p></dd><dt><span class="term"><span class="command"><strong>-xdocs</strong></span></span></dt><dd><p>
Produce the bug reports in xdoc XML format for use with Apache Maven.
</p></dd><dt><span class="term"><span class="command"><strong>-output</strong></span> <em class="replaceable"><code>filename</code></em></span></dt><dd><p>
Produce the output in the specified file.
</p></dd><dt><span class="term"><span class="command"><strong>-outputFile</strong></span> <em class="replaceable"><code>filename</code></em></span></dt><dd><p>
This argument is deprecated. Use <span class="command"><strong>-output</strong></span> instead.
</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>
This option enables or disables scanning of nested jar and zip files found in
the list of files and directories to be analyzed.
By default, scanning of nested jar/zip files is enabled.
To disable it, add <span class="command"><strong>-nested:false</strong></span> to the command line
arguments.
</p></dd><dt><span class="term"><span class="command"><strong>-auxclasspath</strong></span> <em class="replaceable"><code>classpath</code></em></span></dt><dd><p>
Set the auxiliary classpath for analysis. This classpath should include all
jar files and directories containing classes that are part of the program
being analyzed but you do not want to have analyzed for bugs.
</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>
Set the path of the user preferences file to use, which might override some of the options abobe.
Specifying <code class="literal">userPrefs</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></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>