// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[checkstyle_plugin]]
= The Checkstyle Plugin

The Checkstyle plugin performs quality checks on your project's Java source files using https://checkstyle.org/index.html[Checkstyle] and generates reports from these checks.

[[sec:checkstyle_usage]]
== Usage

To use the Checkstyle plugin, include the following in your build script:

====
include::sample[dir="snippets/reference/core-plugins/codeQuality/kotlin",files="build.gradle.kts[tags=use-checkstyle-plugin]"]
include::sample[dir="snippets/reference/core-plugins/codeQuality/groovy",files="build.gradle[tags=use-checkstyle-plugin]"]
====

The plugin adds a number of tasks to the project that perform the quality checks. You can execute the checks by running `gradle check`.

Note that Checkstyle will run with the same Java version used to run Gradle.

[[sec:checkstyle_tasks]]
== Tasks

The Checkstyle plugin adds the following tasks to the project:

`checkstyleMain` — link:{groovyDslPath}/org.gradle.api.plugins.quality.Checkstyle.html[Checkstyle]::
_Depends on_: `classes`
+
Runs Checkstyle against the production Java source files.

`checkstyleTest` — link:{groovyDslPath}/org.gradle.api.plugins.quality.Checkstyle.html[Checkstyle]::
_Depends on_: `testClasses`
+
Runs Checkstyle against the test Java source files.

`checkstyle__SourceSet__` — link:{groovyDslPath}/org.gradle.api.plugins.quality.Checkstyle.html[Checkstyle]::
_Depends on_: `__sourceSet__Classes`
+
Runs Checkstyle against the given source set's Java source files.

[[sec:checkstyle_dependencies_added_to_other_tasks]]
=== Dependencies added to other tasks

The Checkstyle plugin adds the following dependencies to tasks defined by the Java plugin.

`check`::
_Depends on_: All Checkstyle tasks, including `checkstyleMain` and `checkstyleTest`.

[[sec:checkstyle_project_layout]]
== Project layout

By default, the Checkstyle plugin expects configuration files to be placed in the root project, but this can be changed.

[source,text]
----
<root>
└── config
    └── checkstyle           // <1>
        └── checkstyle.xml   // <2>
        └── suppressions.xml
----
<1> Checkstyle configuration files go here
<2> Primary Checkstyle configuration file

[[sec:checkstyle_dependency_management]]
== Dependency management

The Checkstyle plugin adds the following dependency configurations:

.Checkstyle plugin - dependency configurations
[cols="a,a", options="header"]
|===
| Name
| Meaning

| `checkstyle`
| The Checkstyle libraries to use
|===

By default, the `checkstyle` configuration uses link:https://mvnrepository.com/artifact/com.puppycrawl.tools/checkstyle[`com.puppycrawl.tools:checkstyle`].
The version of `com.puppycrawl.tools:checkstyle` used is derived from the extension's tool version:

[source,kotlin]
----
checkstyle {
    toolVersion = "10.12.4"
}
----

If another dependency is added, the default `com.puppycrawl.tools:checkstyle` dependency will be removed:

====
include::sample[dir="snippets/reference/core-plugins/checkstylePlugin-dependencies/kotlin",files="build.gradle.kts[tags=replace-dependency]"]
include::sample[dir="snippets/reference/core-plugins/checkstylePlugin-dependencies/groovy",files="build.gradle[tags=replace-dependency]"]
====

To add a dependency to the `checkstyle` configuration while also retaining a dependency on `com.puppycrawl.tools:checkstyle`, use the following solution:

====
include::sample[dir="snippets/reference/core-plugins/checkstylePlugin-dependencies/kotlin",files="build.gradle.kts[tags=add-dependency]"]
include::sample[dir="snippets/reference/core-plugins/checkstylePlugin-dependencies/groovy",files="build.gradle[tags=add-dependency]"]
====

[[sec:checkstyle_configuration]]
== Configuration

See the link:{groovyDslPath}/org.gradle.api.plugins.quality.CheckstyleExtension.html[CheckstyleExtension] class in the API documentation for comprehensive configuration options.

[[sec:checkstyle_configuration_toolchains]]
=== Configuring Checkstyle with Java Toolchains

Checkstyle imposes a minimum requirement of JDK 11, with an anticipated transition to JDK 17 in forthcoming releases. For projects targeting earlier JDK versions, such as JDK 8, this presents a compatibility challenge. Historically, users have resorted to backport dependencies (e.g., `com.puppycrawl.tools:checkstyle-backport-jre8`) to bridge this gap. However, as both Checkstyle and Gradle align with modern Java versions, a more robust and future-proof solution is available through Gradle's Java toolchains.

By leveraging the `javaLauncher` property, you can explicitly configure Checkstyle tasks to execute with a designated JDK version, independent of the JDK used for your project’s compilation or Gradle’s runtime. The following configuration ensures that Checkstyle operates with JDK 17:

[source,groovy]
----
tasks.withType(Checkstyle).configureEach {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
    }
}
----

This approach offers several advantages:

- **Decoupling**: Checkstyle execution is isolated from the project's JDK, enabling compatibility without altering your build’s core environment.
- **Automation**: Gradle’s toolchain support automatically provisions the specified JDK, streamlining setup and ensuring consistency across environments.
- **Sustainability**: It eliminates reliance on community-maintained backports, which may lag behind official releases or introduce maintenance overhead.

We strongly recommend adopting this configuration as the preferred method for managing Checkstyle’s JDK requirements, particularly as the ecosystem progresses toward JDK 17 and beyond.

[[sec:checkstyle_built_in_variables]]
=== Built-in variables

The Checkstyle plugin defines a `config_loc` property that can be used in Checkstyle configuration files to define paths to other configuration files like `suppressions.xml`.

====
include::sample[dir="snippets/reference/core-plugins/codeQuality/groovy/config/checkstyle",files="checkstyle.xml[tags=use-config-loc]"]
====

[[sec:checkstyle_customize_xsl]]
== Customizing the HTML report

The HTML report generated by the link:{groovyDslPath}/org.gradle.api.plugins.quality.Checkstyle.html[Checkstyle] task can be customized using a XSLT stylesheet, for example to highlight specific errors or change its appearance:

====
include::sample[dir="snippets/reference/core-plugins/codeQuality/kotlin",files="build.gradle.kts[tags=customize-checkstyle-report]"]
include::sample[dir="snippets/reference/core-plugins/codeQuality/groovy",files="build.gradle[tags=customize-checkstyle-report]"]
====

https://github.com/checkstyle/contribution/tree/master/xsl[View a sample Checkstyle stylesheet.]

[[sec:enable_checkstyle_sarif]]
== Generate SARIF report

link:https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html[SARIF] report is supported on Checkstyle versions 10.3.3 and newer. It is not enabled by default.

====
include::sample[dir="snippets/reference/core-plugins/codeQuality/kotlin",files="build.gradle.kts[tags=enable-checkstyle-sarif-report]"]
include::sample[dir="snippets/reference/core-plugins/codeQuality/groovy",files="build.gradle[tags=enable-checkstyle-sarif-report]"]
====

[[sec:checkstyle_customize_memory]]
== Changing the amount of memory given to Checkstyle

Checkstyle analysis is performed in a separate process. By default, the Checkstyle process is given a max heap of 512MB. When analyzing many source files, you may need to provide additional memory to this process.
You can change the amount of memory for Checkstyle by configuring the link:{groovyDslPath}/org.gradle.api.plugins.quality.Checkstyle.html#org.gradle.api.plugins.quality.Checkstyle:maxHeapSize[Checkstyle.maxHeapSize].

====
include::sample[dir="snippets/reference/core-plugins/codeQuality/kotlin",files="build.gradle.kts[tags=customize-checkstyle-memory]"]
include::sample[dir="snippets/reference/core-plugins/codeQuality/groovy",files="build.gradle[tags=customize-checkstyle-memory]"]
====
