sbt-findbugs

An sbt 1.x and 0.13.x plugin for running SpotBugs/FindBugs on Java classes. For more information about SpotBugs, see https://spotbugs.github.io.

This plugin currently uses SpotBugs version 3.1.12.

Getting started

Add sbt-findbugs as a plugin in your projects project/plugins.sbt:

addSbtPlugin("uk.co.josephearl" % "sbt-findbugs" % "<version>")

The plugin version depends on the sbt version you are using (you can check this with sbt sbt-version):

sbt version	sbt-findbugs version
1.x	2.5.0
0.13.x	2.4.3

sbt-findbugs is an AutoPlugin, so there is no need to modify the build.sbt file to enable it.

Usage

You can run SpotBugs over your Java classes with the findbugs task. You can run SpotBugs over your Java test classes with the test:findbugs task.

The SpotBugs report is output to target/findbugs-report.xml by default. This can be changed by setting the value of findbugsReportPath. By default test:findbugs outputs to target/findbugs-test-report.xml, this can be changed by setting the value of findbugsReportPath in Test.

You can define include/exclude filters either inline in the build.sbt or in an external XML file.

Defining filters inline

You can include or exclude bug detection for particular classes and methods using filters with the settings findbugsIncludeFilters and findbugsExcludeFilters.

Just use Scala inline XML for the setting, for example:

findbugsIncludeFilters := Some(<FindBugsFilter>
  <Match>
    <Class name="uk.co.josephearl.example.Example" />
  </Match>
</FindBugsFilter>)

Defining filters using filter files

You can also read the filter settings from files in a more conventional way:

findbugsIncludeFilters := Some(scala.xml.XML.loadFile(baseDirectory.value / "findbugs-include-filters.xml"))

Plugins

To use SpotBugs plugins such as fb-contrib or find-sec-bugs use the findbugsPluginList setting:

libraryDependencies += "com.mebigfatguy.fb-contrib" % "fb-contrib" % "7.4.6"

findbugsPluginList += s"${ivyPaths.value.ivyHome.get.absolutePath}/cache/com.mebigfatguy.fb-contrib/fb-contrib/jars/fb-contrib-7.4.6.jar"

Or download the plugins to your projects lib directory:

findbugsPluginList += file("lib/fb-contrib-7.4.6.jar").absolutePath

Running SpotBugs automatically

To run SpotBugs automatically after compilation add the following to your build.sbt:

(findbugs in Compile) := ((findbugs in Compile) triggeredBy (compile in Compile)).value

To run SpotBugs automatically after test compilation:

(findbugs in Test) := ((findbugs in Test) triggeredBy (compile in Test)).value

Failing the build

You can set SpotBugs to fail the build if any bugs are found by setting findbugsFailOnError in your your build.sbt:

findbugsFailOnError := true

This setting is only compatible with findbugsReportType := Some(FindBugsReportType.Xml) (the default) or Some(FindBugsReportType.XmlWithMessages).

Generating an HTML report and failing the build

Although you cannot currently use findbugsFailOnError := true in combination with findbugsReportType := Some(FindBugsReportType.Html), you can use the XSLT transformations functionality to achieve the same result:

findbugsReportType := Some(FindBugsReportType.XmlWithMessages)
findbugsXsltTransformations := Some(Set(FindBugsXSLTTransformation(baseDirectory(_ / "xsl" / "default.xsl").value, target(_ / "findbugs-report.html").value)))
findbugsFailOnError := true

XSLT transformations

The findbugsXsltTransformations setting allows applying XSLT transformations to the XML report generated by SpotBugs. For instance, this could be used to generate a more readable HTML report. This setting takes values of Option[Set[FindBugsXSLTTransformation]], so multiple transformations can be applied.

You can set findbugsXsltTransformations in your build.sbt, for example to generate an HTML report:

findbugsXsltTransformations := Some(Set(FindBugsXSLTTransformation(baseDirectory(_ / "xsl" / "default.xsl").value, target(_ / "findbugs-report.html").value)))

This setting is only compatible with findbugsReportType := Some(FindBugsReportType.Xml) (the default) or Some(FindBugsReportType.XmlWithMessages).

SpotBugs comes with a number of default XSL files which you can use, these are found in findbugs/src/xsl.

Integration tests

If you want to run SpotBugs on your integration tests add the following to your build.sbt:

lazy val root = (project in file(".")).configs(IntegrationTest)

Defaults.itSettings

findbugs in IntegrationTest := findbugsTask(IntegrationTest).value,
findbugsReportPath in IntegrationTest := Some(target(_ / "findbugs-integration-test-report.xml").value)
findbugsAnalyzedPath in IntegrationTest := Seq((classDirectory in IntegrationTest).value)
findbugsAuxiliaryPath in IntegrationTest := (dependencyClasspath in IntegrationTest).value.files

Settings

findbugsReportType

• Description: Optionally selects the output format for the SpotBugs report.
• Accepts: Some(FindBugsReportType.{Xml, XmlWithMessages, Html, PlainHtml, FancyHtml, FancyHistHtml, Emacs, Xdoc})
• Default: Some(FindBugsReportType.Xml)

findbugsReportPath

• Description: Target path of the report file to generate (optional).
• Accepts: any legal file path
• Default: Some(target.value / "findbugs-report.xml")

findbugsPriority

• Description: Suppress reporting of bugs based on priority.
• Accepts: FindBugsPriority.{Relaxed, Low, Medium, High}
• Default: FindBugsPriority.Medium

findbugsEffort

• Description: Decide how much effort to put into analysis.
• Accepts: FindBugsEffort.{Minimum, Default, Maximum}
• Default: FindBugsEffort.Default

findbugsOnlyAnalyze

• Description: Optionally, define which packages/classes should be analyzed.
• Accepts: An option containing a List[String] of packages and classes.
• Default: None (meaning: analyze everything).

findbugsMaxMemory

• Description: Maximum amount of memory to allow for SpotBugs (in MB).
• Accepts: any reasonable amount of memory as an integer value
• Default: 1024

findbugsAnalyzeNestedArchives

• Description: Whether SpotBugs should analyze nested archives or not.
• Accepts: true and false
• Default: true

findbugsSortReportByClassNames

• Description: Whether the reported bug instances should be sorted by class name or not.
• Accepts: true and false
• Default: false

findbugsFailOnError

• Description: Whether the build should be failed if there are any reported bug instances. Only compatible with findbugsReportType := Some(FindBugsReportType.Xml) or Some(FindBugsReportType.XmlWithMessages).
• Accepts: true and false
• Default: false

findbugsIncludeFilters

• Description: Optional filter file XML content defining which bug instances to include in the static analysis.
• Accepts: None and Option[Node]
• Default: None (no include filters).

findbugsExcludeFilters

• Description: Optional filter file XML content defining which bug instances to exclude in the static analysis.
• Accepts: None and Some[Node]
• Default: None (no exclude filters).

findbugsAnalyzedPath

• Description: The path to the classes to be analyzed.
• Accepts: any sbt.Path
• Default: Seq(classDirectory in Compile value)

findbugsPluginList

• Description: A list of SpotBugs plugins to enable, can be an absolute path to a plugin or the name of a plugin in the SpotBugs optional plugins directory ~/.findbugs/optionalPlugin.
• Accepts: any Seq[String]
• Default: Seq()

findbugsXsltTransformations

• Description: A set of XSLT transformations to apply to the report. Only compatible with findbugsReportType := Some(FindBugsReportType.Xml) or Some(FindBugsReportType.XmlWithMessages).
• Accepts: any Option[Set[FindBugsXSLTTransformation]]
• Default: None