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-0.9.1.tar.gz | tar xvf -
Extracting a zip format distribution:
C:\Software>unzip findbugs-0.9.1.zip
Usually, extracting a binary distribution will create a directory ending in findbugs-0.9.1. 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-0.9.1. This directory is the FindBugs home directory. We'll refer to it as $FINDBUGS_HOME 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/findbugs options...
On Windows systems, the command to invoke the wrapper script is
C:\My Directory>$FINDBUGS_HOME\bin\findbugs.bat options...
On both Unix-like and Windows systems, you can simply add the $FINDBUGS_HOME/bin directory to your PATH 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.
Specifies arguments to pass to the JVM. For example, you might want to set a JVM property:
$ findbugs -textui -jvmArgs "-Duser.language=ja" myApp.jar
Specifies the directory containing the JRE (Java Runtime Environment) to use to execute FindBugs.
Specifies 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.
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.
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.
These options are only accepted by the Graphical User Interface.
Set Swing look and feel.
These options are only accepted by the Text User Interface.
Sort reported bug instances by class name.
Only report bug instances that match the filter specified by filterFile.xml. See Chapter 8, Filter Files.
Report all bug instances except those matching the filter specified by filterFile.xml. See Chapter 8, Filter Files.
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.)
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 distribution. If you want to specify your own XSLT stylesheet to perform the transformation, 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.
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.