<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 2. Installing and Running FindBugs™</title><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="introduction.html" title="Chapter 1. Introduction"><link rel="next" href="building.html" title="Chapter 3. Building FindBugs™ from Source"></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 2. Installing and Running <span class="application">FindBugs</span>™</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="building.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="installing"></a>Chapter 2. Installing and 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="installing.html#d0e104">1. Extracting the Distribution</a></span></dt><dt><span class="sect1"><a href="installing.html#d0e158">2. Configuration</a></span></dt><dt><span class="sect1"><a href="installing.html#commandLineOptions">3. Command Line Options</a></span></dt></dl></div><p>
This chapter explains how to install and run <span class="application">FindBugs</span>.
</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e104"></a>1. Extracting the Distribution</h2></div></div></div><p>
The easiest way to install <span class="application">FindBugs</span> is to download a binary distribution.
Binary distributions are available in
<a href="http://prdownloads.sourceforge.net/findbugs/findbugs-1.2.1.tar.gz?download" target="_top">gzipped tar format</a> and
<a href="http://prdownloads.sourceforge.net/findbugs/findbugs-1.2.1.zip?download" target="_top">zip format</a>.
Once you have downloaded a binary distribution, extract it into a directory of your choice.
</p><p>
Extracting a gzipped tar format distribution:
</p><pre class="screen">
<code class="prompt">$ </code><span><strong class="command">gunzip -c findbugs-1.2.1.tar.gz | tar xvf -</strong></span>
</pre><p>
</p><p>
Extracting a zip format distribution:
</p><pre class="screen">
<code class="prompt">C:\Software></code><span><strong class="command">unzip findbugs-1.2.1.zip</strong></span>
</pre><p>
</p><p>
Usually, extracting a binary distribution will create a directory ending in
<code class="filename">findbugs-1.2.1</code>. For example, if you extracted
the binary distribution from the <code class="filename">C:\Software</code>
directory, then the <span class="application">FindBugs</span> software will be extracted into the directory
<code class="filename">C:\Software\findbugs-1.2.1</code>.
This directory is the <span class="application">FindBugs</span> home directory. We'll refer to it as
<em class="replaceable"><code>$FINDBUGS_HOME</code></em> throughout this manual.
</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e158"></a>2. Configuration</h2></div></div></div><p>
Once you have extracted the binary distribution, all you need to do in order
to run <span class="application">FindBugs</span> is to invoke the 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><strong class="command"><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><strong class="command"><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><strong class="command">findbugs</strong></span> command.
</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="commandLineOptions"></a>3. Command Line Options</h2></div></div></div><p>
There are two ways to invoke <span class="application">FindBugs</span>. The first invokes the the Graphical User Interface (GUI):
</p><pre class="screen">
<code class="prompt">$ </code><span><strong class="command">findbugs <em class="replaceable"><code>[standard options]</code></em> <em class="replaceable"><code>[GUI options]</code></em></strong></span>
</pre><p>
The second invokes the Command Line Interface (Text UI):
</p><pre class="screen">
<code class="prompt">$ </code><span><strong class="command">findbugs -textui <em class="replaceable"><code>[standard options]</code></em> <em class="replaceable"><code>[Text UI options]</code></em></strong></span>
</pre><p>
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e241"></a>3.1. Standard options</h3></div></div></div><p>
These options may be used with both the GUI and Text UI.
</p><div class="variablelist"><dl><dt><span class="term"><span><strong class="command">-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><strong class="command">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><strong class="command">-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><strong class="command">-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><strong class="command">-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><strong class="command">-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><strong class="command">-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><strong class="command">-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 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><dt><span class="term"><span><strong class="command">-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>.
</p></dd></dl></div><p>
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e344"></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><strong class="command">-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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e360"></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><strong class="command">-sortByClass</strong></span></span></dt><dd><p>
Sort reported bug instances by class name.
</p></dd><dt><span class="term"><span><strong class="command">-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 href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>.
</p></dd><dt><span class="term"><span><strong class="command">-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 href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>.
</p></dd><dt><span class="term"><span><strong class="command">-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><strong class="command">-low</strong></span></span></dt><dd><p>
Report all bugs.
</p></dd><dt><span class="term"><span><strong class="command">-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><strong class="command">-high</strong></span></span></dt><dd><p>
Report only high priority bugs.
</p></dd><dt><span class="term"><span><strong class="command">-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><strong class="command">-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><strong class="command">-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><strong class="command">-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 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><strong class="command">-html:plain.xsl</strong></span>, <span><strong class="command">-html:fancy.xsl</strong></span> and <span><strong class="command">-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><strong class="command">fancy-hist.xsl</strong></span> an evolution of <span><strong class="command">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><strong class="command">-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><strong class="command">-emacs</strong></span></span></dt><dd><p>
Produce the bug reports in Emacs format.
</p></dd><dt><span class="term"><span><strong class="command">-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><strong class="command">-outputFile</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><strong class="command">-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><strong class="command">-nested:false</strong></span> to the command line
arguments.
</p></dd><dt><span class="term"><span><strong class="command">-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></dl></div><p>
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="building.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Building <span class="application">FindBugs</span>™ from Source</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
contrib-release
>
by-pkgid
>
95f5ae0ce06780fd3cab0be9375c9914
>
files
>
52
