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).
Add the following lines to project/plugins.sbt
:
addSbtPlugin("software.purpledragon" % "sbt-checkstyle-plugin" % "<version>")
Checkstyle will be enabled by default for projects.
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
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")
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
.
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
.
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"
- Description: The location of the generated checkstyle report.
- Accepts:
File
- Default:
target.value / "checkstyle-report.xml"
- Description: The location of the checkstyle configuration file.
- Accepts:
CheckstyleConfigLocation
(.File
,.URL
,.Classpath
) - Default:
CheckstyleConfigLocation.File("checkstyle-config.xml")
- Description: A set of XSLT transformations to be applied to the checkstyle output.
- Accepts:
Set[CheckstyleXSLTSettings]
- Default:
Set.empty
- Description: Decide how much effort to put into analysis.
- Accepts:
CheckstyleSeverityLevel
(Ignore
,Info
,Warning
,Error
) - Default:
CheckstyleSeverityLevel.Ignore