| <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></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> |
