Table of Contents
FindBugs 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.
![[Warning]](warning.png) | Warning |
|---|---|
This chapter is in the process of being re-written. The rewrite is not complete yet. |
If you are running FindBugs on a Windows system,
double-click on the file %FINDBUGS_HOME%\lib\findbugs.jar
On a Unix, Linux, or Mac OS X system, run the $FINDBUGS_HOME/bin/findbugs
java -jar $FINDBUGS_HOME/lib/findbugs.jarto run the FindBugs GUI.
Refer to Chapter 5, Using the FindBugs GUI for information on how to use the GUI.
This section describes how to invoke the FindBugs program. There are two ways to invoke FindBugs: directly, or using a wrapper script.
The preferred method of running FindBugs is to directly execute
$FINDBUGS_HOME/lib/findbugs.jar
The general syntax of invoking FindBugs directly is the following:
java [JVM arguments] -jar $FINDBUGS_HOME/lib/findbugs.jar options...
The first command line option chooses the FindBugs user interface to execute. Possible values are:
-gui: runs the graphical user interface (GUI)
-textui: runs the command line user interface
-version: displays the FindBugs version number
-help: displays help information for the FindBugs command line user interface
-gui1: executes the original (obsolete) FindBugs graphical user interface
Several Java Virtual Machine arguments are useful when invoking FindBugs.
- -Xmx
NNm Set the maximum Java heap size to
NNmegabytes. FindBugs generally requires a large amount of memory. For a very large project, using 1500 megabytes is not unusual.- -D
name=value Set a Java system property. For example, you might use the argument -Duser.language=ja to display GUI messages in Japanese.
Another way to run FindBugs is to use a 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.
The FindBugs wrapper scripts support the following command-line options. Note that these command line options are not handled by the FindBugs program per se; rather, they are handled by the wrapper script.
- -jvmArgs
args 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- -javahome
directory Specifies the directory containing the JRE (Java Runtime Environment) to use to execute FindBugs.
- -maxHeap
size Specifies the maximum Java heap size in megabytes. The default is 256. More memory may be required to analyze very large programs or libraries.
- -debug
Prints a trace of detectors run and classes analyzed to standard output. Useful for troubleshooting unexpected analysis failures.
- -property
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=valuestring must be in quotes.
This section describes the command line options supported by FindBugs. These command line options may be used when invoking FindBugs directly, or when using a wrapper script.
These options may be used with both the GUI and command-line interfaces.
- -effort:min
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.
- -effort:max
Enable analyses which increase precision and find more bugs, but which may require more memory and take more time to complete.
- -project
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
.fbor.fbp.
These options are only accepted by the Graphical User Interface.
- -look:
plastic|gtk|native Set Swing look and feel.
These options are only accepted by the Text User Interface.
- -sortByClass
Sort reported bug instances by class name.
- -include
filterFile.xml Only report bug instances that match the filter specified by
filterFile.xml. See Chapter 8, Filter Files.- -exclude
filterFile.xml Report all bug instances except those matching the filter specified by
filterFile.xml. See Chapter 8, Filter Files.- -onlyAnalyze
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
importstatement to import all classes in the package (i.e., add.*to the full name of the package). Replace.*with.-to also analyze all subpackages.- -low
Report all bugs.
- -medium
Report medium and high priority bugs. This is the default setting.
- -high
Report only high priority bugs.
- -relaxed
Relaxed reporting mode. For many detectors, this option suppresses the heuristics used to avoid reporting false positives.
- -xml
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.
- -html
Generate HTML output. By default, FindBugs will use the
default.xslXSLT stylesheet to generate the HTML: you can find this file infindbugs.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. Theplain.xslstylesheet does not use Javascript or DOM, and may work better with older web browsers, or for printing. Thefancy.xslstylesheet 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, wheremyStylesheet.xslis the filename of the stylesheet you want to use.- -emacs
Produce the bug reports in Emacs format.
- -xdocs
Produce the bug reports in xdoc XML format for use with Apache Maven.
- -output
filename Produce the output in the specified file.
- -outputFile
filename This argument is deprecated. Use -output instead.
- -nested
[: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.
- -auxclasspath
classpath 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.
- -auxclasspathFromInput
Read the auxiliary classpath for analysis from standard input, each line adds new entry to the auxiliary classpath for analysis.
- -auxclasspathFromFile
filepath Read the auxiliary classpath for analysis from file, each line adds new entry to the auxiliary classpath for analysis.
- -analyzeFromFile
filepath Read the files to analyze from file, each line adds new entry to the classpath for analysis.
- -userPrefs
edu.umd.cs.findbugs.core.prefs Set the path of the user preferences file to use, which might override some of the options abobe. Specifying
userPrefsas first argument would mean some later options will override them, as last argument would mean they will override some previous options). This rationale behind this option is to reuse FindBugs Eclipse project settings for command line execution.