// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.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:

.Using the Checkstyle plugin
====
include::sample[dir="snippets/codeQuality/codeQuality/groovy",files="build.gradle[tags=use-checkstyle-plugin]"]
include::sample[dir="snippets/codeQuality/codeQuality/kotlin",files="build.gradle.kts[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.

=== 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.

----
<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
|===


[[sec:checkstyle_configuration]]
== Configuration

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


[[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`.

.Using the config_loc property
====
include::sample[dir="snippets/codeQuality/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:

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

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