This chapter explains how to install and run FindBugs.
The easiest way to install FindBugs is to download a binary distribution. Binary distributions are available in gzipped tar format and zip format. Once you have downloaded a binary distribution, extract it into a directory of your choice.
Extracting a gzipped tar format distribution:
$ gunzip -c findbugs-1.3.4.tar.gz | tar xvf -
Extracting a zip format distribution:
C:\Software>unzip findbugs-1.3.4.zip
Usually, extracting a binary distribution will create a directory ending in
findbugs-1.3.4. For example, if you extracted
the binary distribution from the C:\Software
directory, then the FindBugs software will be extracted into the directory
C:\Software\findbugs-1.3.4.
This directory is the FindBugs home directory. We'll refer to it as
$FINDBUGS_HOME (or %FINDBUGS_HOME% for Windows) throughout this manual.
Once you have extracted the binary distribution, all you need to do in order to run FindBugs is to invoke the wrapper script.
On Unix-like systems, use the following command to invoke the wrapper script:
$$FINDBUGS_HOME/bin/findbugsoptions...
On Windows systems, the command to invoke the wrapper script is
C:\My Directory>%FINDBUGS_HOME%\bin\findbugs.batoptions...
On both Unix-like and Windows systems, you can simply add the $FINDBUGS_HOME/binPATH environment variable and then invoke
FindBugs using the findbugs command.
There are two ways to invoke FindBugs. The first invokes the the Graphical User Interface (GUI):
$findbugs[standard options][GUI options]
The second invokes the Command Line Interface (Text UI):
$findbugs -textui[standard options][Text UI options]
These options may be used with both the GUI and Text UI.
argsSpecifies arguments to pass to the JVM. For example, you might want to set a JVM property:
$findbugs -textui -jvmArgs "-Duser.language=ja"myApp.jar
directorySpecifies the directory containing the JRE (Java Runtime Environment) to use to execute FindBugs.
sizeSpecifies the maximum Java heap size in megabytes. The default is 256. More memory may be required to analyze very large programs or libraries.
Prints a trace of detectors run and classes analyzed to standard output. Useful for troubleshooting unexpected analysis failures.
This option disables analyses that increase precision but also increase memory consumption. You may want to try this option if you find that FindBugs runs out of memory, or takes an unusually long time to complete its analysis.
Enable analyses which increase precision and find more bugs, but which may require more memory and take more time to complete.
name=value
This option sets a system property. FindBugs uses system properties
to configure analysis options. See Chapter 9, Analysis Properties.
You can use this option multiple times in order to set multiple properties.
Note: In most versions of Windows, the name=value
string must be in quotes.
project
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 .fb or .fbp.
These options are only accepted by the Graphical User Interface.
plastic|gtk|nativeSet Swing look and feel.
These options are only accepted by the Text User Interface.
Sort reported bug instances by class name.
filterFile.xml
Only report bug instances that match the filter specified by filterFile.xml.
See Chapter 8, Filter Files.
filterFile.xml
Report all bug instances except those matching the filter specified by filterFile.xml.
See Chapter 8, Filter Files.
com.foobar.MyClass,com.foobar.mypkg.*
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 import statement to
import all classes in the package (i.e., add .*
to the full name of the package).
Replace .* with .- to also
analyze all subpackages.
Report all bugs.
Report medium and high priority bugs. This is the default setting.
Report only high priority bugs.
Relaxed reporting mode. For many detectors, this option suppresses the heuristics used to avoid reporting false positives.
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 -xml:withMessages; 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.
Generate HTML output. By default, FindBugs will use the default.xsl
XSLT
stylesheet to generate the HTML: you can find this file in findbugs.jar,
or in the FindBugs source or binary distributions. Variants of this option include
-html:plain.xsl, -html:fancy.xsl and -html:fancy-hist.xsl.
The plain.xsl stylesheet does not use Javascript or DOM,
and may work better with older web browsers, or for printing. The fancy.xsl
stylesheet uses DOM and Javascript for navigation and CSS for
visual presentation. The fancy-hist.xsl an evolution of fancy.xsl stylesheet.
It makes an extensive use of DOM and Javascript for dynamically filtering the lists of bugs.
If you want to specify your own
XSLT stylesheet to perform the transformation to HTML, specify the option as
-html:myStylesheet.xsl,
where myStylesheet.xsl is the filename of the
stylesheet you want to use.
Produce the bug reports in Emacs format.
Produce the bug reports in xdoc XML format for use with Apache Maven.
filenameProduce the output in the specified file.
filenameThis argument is deprecated. Use -output instead.
[:true|false]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 -nested:false to the command line arguments.
classpathSet 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.