4. 运行 FindBugs™

FindBugs 有两个用户界面：图形用户界面（GUI）和命令行用户界面。本章介绍如何运行这两个用户界面。

$警告$	警告
	本章正在重写过程中，重写尚未完成。

1. 快速入门

如果您在 Windows 系统上运行 FindBugs，只需双击文件 %FINDBUGS_HOME% \lib\findbugs.jar 即可启动 FindBugs 图形用户界面。

在 Unix、Linux 或 Mac OS X 系统上，请运行 $FINDBUGS_HOME /bin/findbugs 脚本，或运行命令

java -jar  $FINDBUGS_HOME /lib/findbugs.jar

要启动 FindBugs GUI。

有关如何使用 GUI 的信息，请参阅第 5 章，使用 FindBugs GUI。

2. 执行 FindBugs

本节介绍如何调用 FindBugs 程序。调用 FindBugs 有两种方式：直接调用，或使用包装脚本。

2.1. 直接调用 FindBugs

运行 FindBugs 的首选方式是使用 java 可执行程序的 -jar 命令行开关直接执行 $FINDBUGS_HOME /lib/findbugs.jar。（1.3.5 之前的 FindBugs 版本需要使用包装脚本来调用 FindBugs。）

直接调用 FindBugs 的一般语法如下：

    java  [JVM arguments]  -jar  $FINDBUGS_HOME /lib/findbugs.jar  options...

2.1.1. 选择用户界面

第一个命令行选项用于选择要启动的 FindBugs 用户界面。可取的值有：

-gui：启动图形用户界面（GUI）
-textui：启动命令行用户界面
-version：显示 FindBugs 版本号
-help：显示 FindBugs 命令行用户界面的帮助信息
-gui1：执行旧版（已废弃）的 FindBugs 图形用户界面

2.1.2. Java 虚拟机（JVM）参数

调用 FindBugs 时，有几个 Java 虚拟机参数非常有用。

-Xmx NN m

将 Java 堆的最大容量设置为 NN 兆字节。FindBugs 通常需要大量内存。对于非常大的项目，使用 1500 兆字节并不罕见。

-D name = value

设置一个 Java 系统属性。例如，你可以使用参数 -Duser.language=ja 让界面消息以日语显示。

2.2. 使用包装脚本调用 FindBugs

运行 FindBugs 的另一种方式是使用包装脚本。

在类 Unix 系统上，使用以下命令调用包装脚本：

$ $FINDBUGS_HOME /bin/findbugs  options...

在 Windows 系统上，调用包装脚本的命令为

C:\My Directory>%FINDBUGS_HOME% \bin\findbugs.bat  options...

在 Unix 类系统和 Windows 系统上，你只需将 $FINDBUGS_HOME/bin 目录添加到 PATH 环境变量中，然后即可通过 findbugs 命令来调用 FindBugs。

2.2.1. 包装脚本命令行选项

FindBugs 的包装脚本支持以下命令行选项。请注意，这些命令行选项并非由 FindBugs 程序本身处理，而是由包装脚本来处理。

-jvmArgs args

指定要传递给 JVM 的参数。例如，你可能想要设置某个 JVM 属性：

$ findbugs -textui -jvmArgs "-Duser.language=ja"  myApp.jar

-javahome directory

指定包含 JRE（Java 运行环境）的目录，用于执行 FindBugs。

-maxHeap size

指定最大 Java 堆大小（以兆字节为单位）。默认值为 256。分析非常大的程序或库时可能需要更多内存。

-debug

将运行的检测器和分析的类的跟踪信息打印到标准输出。有助于排查分析过程中出现的意外失败。

-property name=value

此选项用于设置系统属性。FindBugs 使用系统属性来配置分析选项。请参阅第 9 章，分析属性。您可以多次使用此选项来设置多个属性。注意：在大多数 Windows 版本中，name=value 字符串必须用引号括起来。

3. 命令行选项

本节描述 FindBugs 支持的命令行选项。这些命令行选项可以在直接调用 FindBugs 时使用，也可以在使用包装脚本时使用。

3.1. 通用命令行选项

这些选项在图形用户界面和命令行界面中均可使用。

-effort:min

此选项会禁用那些能提高精度但也会增加内存消耗的分析。如果发现 FindBugs 出现内存不足，或者完成分析所需时间异常长，可以尝试此选项。

-effort:max

启用能够提高精度并发现更多缺陷的分析，但这些分析可能需要更多内存并花费更长时间才能完成。

-project project

指定要分析的项目。您指定的项目文件应是通过图形用户界面创建的。通常以 .fb 或 .fbp 扩展名结尾。

3.2. 图形用户界面选项

这些选项仅被图形用户界面接受。

-look:plastic|gtk|native

设置 Swing 外观和感觉。

3.3. 文本用户界面选项

这些选项仅被文本用户界面接受。

-sortByClass

按类名对报告的缺陷实例进行排序。

-include filterFile.xml

仅报告与 filterFile.xml 中指定的过滤器相匹配的缺陷实例。请参阅第 8 章，过滤器文件。

-exclude filterFile.xml

报告除与 filterFile.xml 中指定的过滤器相匹配之外的所有缺陷实例。请参阅第 8 章，过滤器文件。

-onlyAnalyze com.foobar.MyClass,com.foobar.mypkg.*

将分析限制为仅查找给定的以逗号分隔的类和包列表中的缺陷。与过滤不同，此选项不会对未显式匹配的类和包运行分析：对于大型项目，这可以大幅缩短运行分析所需的时间。（不过，如果某些检测器没有在整个应用程序上运行，可能会产生不准确的结果。）类应使用其完整类名（包括包）指定，包应按照 Java import 语句中导入包内所有类的方式指定（即，在包的全名后添加 .*）。将 .* 替换为 .- 可同时分析所有子包。

-low

报告所有缺陷。

-medium

报告中等优先级和高优先级的缺陷。这是默认设置。

-high

仅报告高优先级缺陷。

-relaxed

宽松报告模式。对于许多检测器，此选项会抑制用于避免报告误报的启发式方法。

-xml

以 XML 格式生成缺陷报告。生成的 XML 数据可以稍后在 GUI 中查看。你也可以将此选项指定为 -xml:withMessages；使用此选项变体时，XML 输出将包含描述文件中所含警告的人类可读消息。以此方式生成的 XML 文件易于转换为报告。

-html

生成 HTML 输出。默认情况下，FindBugs 将使用 default.xsl XSLT 样式表来生成 HTML：你可以在 findbugs.jar 以及 FindBugs 的源码或二进制发行版中找到此文件。此选项的变体包括 -html:plain.xsl、-html:fancy.xsl 和 -html:fancy-hist.xsl。plain.xsl 样式表不使用 Javascript 或 DOM，可能在旧版浏览器或打印时效果更好。fancy.xsl 样式表使用 DOM 和 Javascript 进行导航，使用 CSS 进行视觉呈现。fancy-hist.xsl 是 fancy.xsl 样式表的演进版本，它大量使用 DOM 和 Javascript 来动态过滤缺陷列表。

如果你想指定自己的 XSLT 样式表来执行到 HTML 的转换，请将选项指定为 -html: myStylesheet.xsl，其中 myStylesheet.xsl 是你要使用的样式表的文件名。

-emacs

以 Emacs 格式生成缺陷报告。

-xdocs

以 xdoc XML 格式生成缺陷报告，供 Apache Maven 使用。

-output filename

将输出生成到指定的文件中。

-outputFile filename

此参数已弃用。请改用 -output。

-nested[:true|false]

此选项启用或禁用对文件和目录分析列表中嵌套的 jar 和 zip 文件的扫描。默认情况下，嵌套 jar/zip 文件的扫描是启用的。要禁用它，请在命令行参数中添加 -nested:false。

-auxclasspath classpath

设置用于分析的辅助类路径。该类路径应包含所有 jar 文件和目录，这些 jar 文件和目录中包含属于被分析程序、但你又不希望对其进行缺陷分析的类。

-auxclasspathFromInput

从标准输入读取用于分析的辅助类路径，每一行会向辅助类路径中添加一个新条目。

-auxclasspathFromFile filepath

从文件读取用于分析的辅助类路径，每一行会向辅助类路径中添加一个新条目。

-analyzeFromFile filepath

从文件读取待分析的文件列表，每一行会向用于分析的类路径中添加一个新条目。

-userPrefs edu.umd.cs.findbugs.core.prefs

设置要使用的用户首选项文件的路径，该文件可能会覆盖上面的某些选项。将 userPrefs 作为第一个参数指定，意味着后面的某些选项会覆盖它；作为最后一个参数指定，则意味着它会覆盖之前的一些选项）。此选项的设计初衷是为了在命令行执行时复用 FindBugs 的 Eclipse 项目设置。