运行 SpotBugs

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

快速入门

如果您在 Windows 系统上运行 SpotBugs，请双击文件 %SPOTBUGS_HOME%\lib\spotbugs.jar 以启动 SpotBugs GUI。

在 Unix、Linux 或 macOS 系统上，请运行 $SPOTBUGS_HOME/bin/spotbugs 脚本，或运行命令 java -jar $SPOTBUGS_HOME/lib/spotbugs.jar 来启动 SpotBugs GUI。

有关如何使用该 GUI 的信息，请参阅 使用 SpotBugs GUI。

运行 SpotBugs

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

直接调用 SpotBugs

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

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

java [JVM arguments] -jar $SPOTBUGS_HOME/lib/spotbugs.jar options...

选择用户界面

第一个命令行选项用于选择要执行的 SpotBugs 用户界面。可选值如下：

-gui:

启动图形用户界面（GUI）

-textui:

运行命令行用户界面

-version:

显示 SpotBugs 版本号。

-help:

显示 SpotBugs 命令行用户界面的帮助信息

-gui1:

执行原有的（已废弃的）SpotBugs 图形用户界面

Java 虚拟机（JVM）参数

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

-XmxNNm:

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

-Dname=value:

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

使用包装脚本调用 SpotBugs

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

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

$ $SPOTBUGS_HOME/bin/spotbugs options...

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

C:\My Directory>%SPOTBUGS_HOME%\bin\spotbugs.bat options...

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

包装脚本的命令行选项

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

-jvmArgs _args_:

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

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

-javahome _directory_:

指定用于执行 FindBugs 的 JRE（Java 运行时环境）所在的目录。

-maxHeap _size_:

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

-debug:

将所运行的检测器和所分析的类的跟踪信息打印到标准输出。对于排查意外的分析失败问题很有帮助。

-property _name=value_:

此选项用于设置系统属性。SpotBugs 使用系统属性来配置分析选项，详见 Analysis Properties。您可以多次使用此选项来设置多个属性。注意：在大多数 Windows 版本中，name=value 字符串必须用引号括起来。

命令行选项

本节介绍 SpotBugs 支持的命令行选项。这些命令行选项既可以在直接调用 SpotBugs 时使用，也可以在使用包装脚本时使用。

通用命令行选项

这些选项既可用于图形用户界面，也可用于命令行界面。

-effort[:min|less|default|more|max]:

设置分析努力级别。-effort:min 会禁用若干能提高精确度但也会增加内存消耗的分析。如果你发现使用 -effort:less 时 SpotBugs 仍然内存耗尽，或完成分析所需时间异常漫长，可以尝试此选项。-effort:less 会禁用一些能提高精确度但也会增加内存消耗的分析。如果你发现使用 -effort:more/-effort:default 时 SpotBugs 会内存耗尽，或完成分析所需时间异常漫长，可以尝试此选项。-effort:more 会运行多项分析以查找缺陷，这也是 -effort:default 的设置。-effort:max 启用那些能提高精确度并发现更多缺陷的分析，但可能需要更多内存和更长的完成时间。参见努力级别。

-project _project_:

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

-pluginList <jar1[;jar2…]>:

指定要加载的插件 Jar 文件列表。

-home <home directory>:

指定 SpotBugs 主目录。

-adjustExperimental:

实验性 Bug 模式的优先级降低。

-workHard:

确保分析强度至少为 ‘default’。

-conserveSpace:

与 -effort:min 相同（为了向后兼容）。

图形界面选项

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

-look:plastic|gtk|native:

设置 Swing 外观。

文本 UI 选项

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

-sortByClass=filepath:

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

从 SpotBugs 4.5.0 起，该选项接收一个文件路径，例如 -sortByClass=path/to/spotbugs.txt。也支持设置多个报告，例如 -xml=spotbugs.xml -sortByClass=spotbugs.txt。

-include _filterFile.xml_:

仅报告与 filterFile.xml 中指定的过滤器相匹配的缺陷实例。参见 过滤器文件。

-exclude _filterFile.xml_:

报告除 filterFile.xml 指定的过滤器所匹配之外的所有错误实例。参见 过滤器文件。

-onlyAnalyze com.foobar.MyClass,com.foobar.mypkg.,!com.foobar.mypkg.ExcludedClass*::

将分析限制在给定的以逗号分隔的类和包列表中。与过滤不同，该选项会避免对未显式匹配的类和包运行分析：对于大型项目，这可以大幅减少运行分析所需的时间。（不过，某些检测器如果没有在整个应用程序上运行，可能会产生不准确的结果。）类应使用其完整类名（包含包名）指定，包的指定方式应与 Java import 语句中导入包内所有类的方式相同（即，在包的完整名称后加上 .*）。将 .* 替换为 .- 可同时分析所有子包。以 ! 开头的项将被视为排除项，从分析中移除原本会被包含的类。

-low:

报告所有缺陷。

-medium:

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

-high:

仅报告高优先级缺陷。

-relaxed:

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

-xml=filepath:

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

从 SpotBugs 4.5.0 起，此选项接受一个文件路径，例如 -xml:withMessages=path/to/spotbugs.xml。也支持设置多个报告，例如 -xml=spotbugs.xml -html=spotbugs.html。

-html=filepath:

生成 HTML 输出。默认情况下，SpotBugs 会使用 default.xsl XSLT 样式表来生成 HTML：你可以在 spotbugs.jar 中找到该文件，也可以在 SpotBugs 的源码或二进制发行版中找到它。此选项的变体包括 -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 是你要使用的样式表的文件名。

从 SpotBugs 4.5.0 开始，此选项接收类似 -html:fancy-hist.xsl=path/to/spotbugs.html 的文件路径。同时也支持设置多个报告，例如 -xml=spotbugs.xml -html=spotbugs.html。

-sarif=filepath:

以 SARIF 2.1.0 格式输出缺陷报告。

从 SpotBugs 4.5.0 开始，该选项接收形如 -sarif=path/to/spotbugs.sarif 的文件路径。也支持通过 -xml=spotbugs.xml -sarif=spotbugs.sarif 设置多份报告。

-emacs=filepath:

以 Emacs 格式生成缺陷报告。

-xdocs=filepath:

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

-output _filename_:

此参数已弃用。请改用报告类型选项，如 -xml=spotbugs.xml。

-outputFile _filename_:

此参数已弃用。请改用报表类型选项 -xml=spotbugs.xml。

-nested[:true|false]:

此选项用于启用或禁用对所分析文件和目录列表中发现的嵌套 jar 和 zip 文件的扫描。默认情况下，嵌套 jar/zip 文件的扫描处于启用状态。要禁用该功能，请在命令行参数中添加 -nested:false。

-auxclasspath _classpath_:

设置分析所用的辅助类路径（auxiliary classpath）。该类路径应包含属于被分析程序、但你并不希望对其检查缺陷的所有 jar 文件和包含类文件的目录。

-auxclasspathFromInput:

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

-auxclasspathFromFile _filepath_:

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

-analyzeFromFile _filepath_:

从文件读取要分析的文件，每一行都会向待分析的 classpath 中添加一个新条目。

-userPrefs _edu.umd.cs.findbugs.core.prefs_:

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

-showPlugins:

显示可用检测器插件的列表。

输出选项

-timestampNow:

将结果的时间戳设置为当前时间。

-quiet:

抑制错误消息。

-longBugCodes:

报告长缺陷代码。

-progress:

在终端窗口中显示进度。

-release <release name>:

设置被分析应用程序的发布名称。

-maxRank <rank>:

仅报告缺陷等级不低于所给值的问题。

-dontCombineWarnings:

不要合并仅行号不同的警告。

-train[:outputDir]:

保存训练数据（实验性）；输出目录默认为 ‘.’。

-useTraining[:inputDir]:

使用训练数据（实验性）；输入目录默认为 ‘.’。

-redoAnalysis <filename>:

使用先前分析的配置重新执行分析。

-sourceInfo <filename>:

指定源信息文件（字段与类的行号）。

-projectName <project name>:

项目的描述性名称。

-reanalyze <filename>:

在提供的文件中重新执行分析。

输出过滤选项

-bugCategories <cat1[,cat2…]>:

只报告指定类别中的缺陷。

-excludeBugs <baseline bugs>:

排除在基线 XML 输出中同样被报告的缺陷。

-applySuppression:

排除任何与从 fbp 文件加载的抑制过滤器相匹配的缺陷。

检测器（访问器）配置选项

-visitors <v1[,v2…]>:

仅运行指定名称的访问器。

-omitVisitors <v1[,v2…]>:

省略具名访问者。

-chooseVisitors <+v1,-v2,…>:

选择性地启用/禁用检测器。

-choosePlugins <+p1,-p2,…>:

选择性地启用/禁用插件。

-adjustPriority <v1=(raise|lower)[,…]>:

提高/降低指定访问者的警告优先级

项目配置选项

-sourcepath <source path>:

设置被分析类的源文件路径。

-exitcode:

设置进程的退出码。

-noClassOk:

如果没有指定任何类，则输出空的警告文件。

-xargs:

从标准输入获取 class 文件/JAR 文件列表，而不是从命令行获取。

-bugReporters <name,name2,-name3>:

可显式启用/禁用的 Bug 报告器装饰器。

-printConfiguration:

打印配置并退出，不执行分析。