Home | History | Annotate | Download | only in manual
      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
      5 command line user interface.  This chapter describes
      6 how 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>
     65 On 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>
     70 On 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>
     75 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>
     76 directory to your <code class="filename">PATH</code> environment variable and then invoke
     77 FindBugs 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>
    108 These 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>
    122 These 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>
    128 These 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>