使用 SpotBugs Ant 任务

本章介绍如何将 SpotBugs 集成到 Ant 的构建脚本中。Ant 是一种流行的 Java 构建与部署工具。通过使用 SpotBugs Ant 任务，你的构建脚本可以自动对 Java 代码运行 SpotBugs。

该 Ant 任务由 Mike Fagan 鼎力贡献。

安装 Ant 任务

要安装 Ant 任务，只需将 $SPOTBUGS_HOME/lib/spotbugs-ant.jar 复制到你的 Ant 安装目录下的 lib 子目录中即可。

强烈建议你使用与该 Ant 任务一同发布的 SpotBugs 版本。我们不保证 Ant 任务的 Jar 文件能在与之一同发布的版本之外的任何 SpotBugs 版本上正常工作。

修改 build.xml

要将 SpotBugs 整合到 build.xml（Ant 的构建脚本）中，首先需要添加一个任务定义。该定义应如下所示：

<taskdef
    resource="edu/umd/cs/findbugs/anttask/tasks.properties"
    classpath="path/to/spotbugs-ant.jar" />

任务定义指定：当在 build.xml 中看到 spotbugs 元素时，应使用所指示的类来执行该任务。

添加任务定义之后，你就可以定义一个使用 spotbugs 任务的 target。以下是一个可以添加到 Apache BCEL 库的 build.xml 中的示例。

<property name="spotbugs.home" value="/export/home/daveho/work/spotbugs" />

<target name="spotbugs" depends="jar">
  <spotbugs home="${spotbugs.home}"
            output="xml"
            outputFile="bcel-sb.xml" >
    <auxClasspath path="${basedir}/lib/Regex.jar" />
    <sourcePath path="${basedir}/src/java" />
    <class location="${basedir}/bin/bcel.jar" />
  </spotbugs>
</target>

spotbugs 元素必须将 home 属性设置为 SpotBugs 的安装目录，换句话说，$SPOTBUGS_HOME。参见 Installing。

该目标会在 bcel.jar 上执行 SpotBugs，这是由 BCEL 的构建脚本生成的 Jar 文件。（通过让它依赖“jar”目标，我们确保在对库运行 SpotBugs 之前库已被完整编译。）SpotBugs 的输出将以 XML 格式保存到名为 bcel-sb.xml 的文件中。一个辅助 Jar 文件 Regex.jar 被添加到辅助类路径中，因为主 BCEL 库引用了它。还指定了源路径，以便所保存的缺陷数据能够准确引用 BCEL 的源代码。

执行任务

下面是一个示例，展示如何从命令行调用 Ant，并使用上文定义的 spotbugs 目标。

[daveho@noir]$ ant spotbugs
Buildfile: build.xml

init:

compile:

examples:

jar:

spotbugs:
 [spotbugs] Running SpotBugs...
 [spotbugs] Bugs were found
 [spotbugs] Output saved to bcel-sb.xml

BUILD SUCCESSFUL
Total time: 35 seconds

在这种情况下，由于我们将缺陷结果保存到了 XML 文件中，因此可以使用 SpotBugs 图形界面来查看结果；参见 Running SpotBugs。

参数

本节介绍在使用 FindBugs 任务时可以指定的参数。

class

一个可选的嵌套元素，用于指定要分析的类。class 元素必须指定 location 属性，用以指明待分析的归档文件（jar、zip 等）、目录或类文件。单个 spotbugs 元素下可以有多个 class 子元素。

除了指定 class 元素之外（或以此替代），SpotBugs 任务还可以包含一个或多个 fileset 元素，用于指定要分析的文件。例如，你可以使用 fileset 来指定分析某个目录下的所有 jar 文件。

auxClasspath

可选的嵌套元素，用于指定类路径（Jar 文件或目录），其中包含被分析库或应用程序所使用、但你不希望被分析的类。其指定方式与 Ant 中 Java 任务的 classpath 元素相同。

sourcePath

一个可选的嵌套元素，用于指定包含源文件的源代码目录路径，这些源文件用于编译被分析的 Java 代码。指定源代码路径后，生成的 XML 缺陷输出将包含完整的源信息，从而可以在 GUI 中进行后续查看。

home

必需属性。必须设置为 SpotBugs 的安装目录名称。

quietErrors

一个可选的布尔属性。如果设置为 true，则会在 SpotBugs 输出中隐藏严重分析错误和缺失类别的报告。默认值为 false。

reportLevel

一个可选属性。它指定了报告问题时的置信度/优先级阈值。如果设置为 low，则不使用置信度过滤缺陷；如果设置为 medium（默认值），则会抑制低置信度的问题；如果设置为 high，则只报告高置信度的缺陷。

output

可选属性。它指定输出格式。如果设置为 xml（默认值），输出为 XML 格式。如果设置为 “xml:withMessages”，输出为包含人类可读消息的 XML 格式。（如果您打算使用 XSL 样式表生成报告，应使用此格式。）如果设置为 “html”，输出为 HTML 格式（默认样式表为 default.xsl）。如果设置为 text，输出为临时文本格式。如果设置为 emacs，输出为 Emacs 错误消息格式。如果设置为 xdocs，输出为供 Apache Maven 使用的 xdoc XML。

stylesheet

可选属性。它指定在输出设置为 html 时用于生成 HTML 输出的样式表。FindBugs 发行版中包含的样式表有 default.xsl、fancy.xsl、fancy-hist.xsl、plain.xsl 和 summary.xsl。如果未提供 stylesheet 属性，则默认值为 default.xsl。

sort

可选属性。如果 output 属性设置为 text，则 sort 属性用于指定报告的 bug 是否按类进行排序。默认值为 true。

outputFile

可选属性。如果指定，则用于命名保存 FindBugs 输出的输出文件。默认情况下，输出会直接由 Ant 显示。

debug

可选布尔属性。如果设置为 true，SpotBugs 会打印诊断信息，说明正在分析哪些类以及正在运行哪些缺陷模式检测器。默认值为 false。

effort

设置分析力度级别。指定的值应为 min、default 或 max 之一。有关设置分析级别的更多信息，请参阅命令行选项 <running.html#command-line-options>。

conserveSpace

effort="min" 的同义词。

workHard

effort="max" 的同义词。

visitors

可选属性。它指定应运行的缺陷检测器的逗号分隔列表。缺陷检测器由其类名指定，不带任何包限定名。默认情况下，会运行所有未被默认禁用的检测器。

omitVisitors

可选属性。它指定一个以逗号分隔的 bug 检测器列表。它与 visitors 属性类似，只是所指定的检测器不会被运行。

chooseVisitors

可选属性。它指定一个以逗号分隔的错误检测器列表，每个检测器前带有“+”或“-”前缀，用于有选择地启用或禁用它们。

excludeFilter

可选属性。它指定过滤文件的文件名，用于排除不希望被报告的缺陷。参见 过滤文件]。

excludePath

一个可选的嵌套元素。它指定一个包含过滤器的路径，这些过滤器用于指定需要从报告中排除的缺陷。参见 过滤器文件。

includeFilter

可选属性。它指定过滤器的文件名，用于规定需要报告哪些缺陷。参见 过滤文件。

includePath

一个可选的嵌套元素。它指定一个包含过滤器的路径，用来指明应报告哪些缺陷。参见 过滤器文件。

projectFile

可选属性。它用于指定项目文件的名称。项目文件由 FindBugs GUI 创建，其中指定了类、辅助类路径条目以及源代码目录。指定项目后，您就不必再指定任何 class 元素，也无需指定 auxClasspath 或 sourcePath 属性。关于如何创建项目，请参阅 运行 SpotBugs⟧。

jvmargs

可选属性。用于指定传递给运行 SpotBugs 的 Java 虚拟机的参数。如果要分析非常大的程序，可能需要使用此属性来指定增加 JVM 可用内存量的标志。

systemProperty

可选的嵌套元素。如果指定了该元素，则用于定义一个系统属性。name 属性指定系统属性的名称，value 属性指定系统属性的值。

timeout

可选属性。它指定执行 SpotBugs 的 Java 进程在被判定为挂起并终止之前可以运行的时间，单位为毫秒。默认值为 600,000 毫秒，即十分钟。请注意，对于非常大的程序，SpotBugs 完成分析可能需要超过十分钟。

failOnError

可选的布尔属性。指定在运行 SpotBugs 出现错误时是否中止构建过程。默认为 false。

errorProperty

可选属性，用于指定一个属性的名称；如果在运行 SpotBugs 时发生错误，该属性将被设置为 true。

warningsProperty

可选属性，用于指定某个属性的名称；如果 SpotBugs 在被分析的程序中报告了任何警告，该属性将被设置为 true。

userPreferencesFile

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

nested

可选属性，用于启用或禁用对所分析文件与目录列表中的嵌套 jar 和 zip 文件的扫描。默认情况下，嵌套 jar/zip 文件的扫描处于启用状态。

setExitCode

可选的布尔属性。退出码是否会被返回给主 Ant 任务。默认为 true。