Hello World!
This commit is contained in:
Ethan Lee
203
findbugs/findbugs-2.0.0/doc/manual/running.html
Normal file
203
findbugs/findbugs-2.0.0/doc/manual/running.html
Normal file
@@ -0,0 +1,203 @@
|
||||
<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#d0e473">1. Quick Start</a></span></dt><dt><span class="sect1"><a href="running.html#d0e511">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="d0e473"></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="d0e511"></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="d0e804"></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="d0e844"></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="d0e860"></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></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>
|
||||
Reference in New Issue
Block a user