sbt-checkstyle-plugin

This project provides an sbt plugin for running Checkstyle over Java source files. For more information about Checkstyle, see checkstyle.sourceforge.io.

This project was forked from etsy/sbt-checkstyle-plugin in 2022 after it became unmaintained. Some initial code was based on an earlier plugin (dead link).

Setup

Add the following lines to project/plugins.sbt:

addSbtPlugin("software.purpledragon" % "sbt-checkstyle-plugin" % "<version>")

Checkstyle will be enabled by default for projects.

Usage

You can run Checkstyle over your Java source files with the checkstyle task. You can run Checkstyle over your Java tests with the Test / checkstyle task.

The Checkstyle configuration file is checkstyle-config.xml by default. This can be changed by setting the value of checkstyleConfigLocation. By default Test / checkstyle uses the same configuration file, but this can be changed by setting the value of Test / checkstyleConfigLocation.

The Checkstyle report is output to target/checkstyle-report.xml by default. This can be changed by setting the value of checkstyleOutputFile. Test / checkstyle outputs to target/checkstyle-test-report.xml, but this can be changed by setting the value of Test / checkstyleOutputFile.

To change the checkstyle configuration file set checkstyleConfigLocation in build.sbt:

checkstyleConfigLocation := CheckstyleConfigLocation.File("checkstyle-config.xml")

You can also load remote configuration files by specifying a URL:

checkstyleConfigLocation :=
  CheckstyleConfigLocation.URL("https://raw.githubusercontent.com/checkstyle/checkstyle/master/config/checkstyle_checks.xml")

Or load configuration files from the classpath by specifying a resource name:

checkstyleConfigLocation := CheckstyleConfigLocation.Classpath("com/etsy/checkstyle-config.xml")

To run Checkstyle automatically after compilation:

(Compile / checkstyle) := (Compile / checkstyle).triggeredBy(Compile / compile).value

To run Checkstyle automatically after test compilation:

(Test / checkstyle) := (Test / checkstyle).triggeredBy(Test / compile).value

XSLT transformations

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

You can set checkstyleXsltTransformations like so in build.sbt:

checkstyleXsltTransformations +=
  CheckstyleXSLTSettings(baseDirectory.value / "checkstyle-noframes.xml", target.value / "checkstyle-report.html")

Failing the build

You can control what severity of issues should break the build by setting the checkstyleSeverityLevel in your build.sbt as follows:

checkstyleSeverityLevel := CheckstyleSeverityLevel.Error

Possible values are defined by the CheckstyleSeverityLevel enumeration. The default is Ignore.

Integration tests

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

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

Defaults.itSettings

checkstyleConfigLocation := CheckstyleConfigLocation.File("my-checkstyle-config.xml")
IntegrationTest / checkstyle := checkstyleTask(IntegrationTest).value
IntegrationTest / checkstyleOutputFile := target.value / "checkstyle-integration-test-report.xml"

You can then run the tasks IntegrationTest / checkstyle and IntegrationTest / checkstyle-check.

Upgrading Checkstyle version

sbt Checkstyle plugin comes with a default Checkstyle version: currently, Checkstyle 6.15 is used by default.

Provided the new Checkstyle version is compatible, you can override the version used at runtime in your project/plugins.sbt:

dependencyOverrides += "com.puppycrawl.tools" % "checkstyle" % "10.3"

Settings

checkstyleOutputFile

• Description: The location of the generated checkstyle report.
• Accepts: File
• Default: target.value / "checkstyle-report.xml"

checkstyleConfigLocation

• Description: The location of the checkstyle configuration file.
• Accepts: CheckstyleConfigLocation (.File, .URL, .Classpath)
• Default: CheckstyleConfigLocation.File("checkstyle-config.xml")

checkstyleXsltTransformations

• Description: A set of XSLT transformations to be applied to the checkstyle output.
• Accepts: Set[CheckstyleXSLTSettings]
• Default: Set.empty

checkstyleSeverityLevel

• Description: Decide how much effort to put into analysis.
• Accepts: CheckstyleSeverityLevel (Ignore, Info, Warning, Error)
• Default: CheckstyleSeverityLevel.Ignore