# The Checkstyle Plugin

version 8.14

The Checkstyle plugin performs quality checks on your project’s Java source files using Checkstyle and generates reports from these checks.

## Usage

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

Example 1. Using the Checkstyle plugin
build.gradle.kts

    plugins {
        checkstyle
    }

build.gradle

    plugins {
        id 'checkstyle'
    }

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.

## Tasks

The Checkstyle plugin adds the following tasks to the project:

`checkstyleMain` — Checkstyle

  Depends on: `classes`

  Runs Checkstyle against the production Java source files.

`checkstyleTest` — Checkstyle

  Depends on: `testClasses`

  Runs Checkstyle against the test Java source files.

`checkstyleSourceSet` — Checkstyle

  Depends on: `sourceSetClasses`

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

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

## Dependency management

The Checkstyle plugin adds the following dependency configurations:

Table 1. Checkstyle plugin - dependency configurations
Name | Meaning
--- | ---
`checkstyle` | The Checkstyle libraries to use

By default, the `checkstyle` configuration uses `com.puppycrawl.tools:checkstyle`. The version of `com.puppycrawl.tools:checkstyle` used is derived from the extension’s tool version:

    checkstyle {
        toolVersion = "10.12.4"
    }

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

    checkstyle {
        toolVersion = "10.12.4"
    }

    dependencies {
        checkstyle "group:artifact:version"
    }

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

    checkstyle {
        toolVersion = "10.12.4"
    }

    dependencies {
        checkstyle "com.puppycrawl.tools:checkstyle:${checkstyle.toolVersion}"
        checkstyle "group:artifact:version"
    }

## Configuration

See the CheckstyleExtension class in the API documentation.

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

Example 2. Using the config_loc property
checkstyle.xml

    <module name="SuppressionFilter">
        <property name="file" value="${config_loc}/suppressions.xml"/>
    </module>

## Customizing the HTML report

The HTML report generated by the Checkstyle task can be customized using a XSLT stylesheet, for example to highlight specific errors or change its appearance:

Example 3. Customizing the HTML report
build.gradle.kts

    tasks.withType<Checkstyle>().configureEach {
        reports {
            xml.required = false
            html.required = true
            html.stylesheet = resources.text.fromFile("config/xsl/checkstyle-custom.xsl")
        }
    }

build.gradle

    tasks.withType(Checkstyle) {
        reports {
            xml.required = false
            html.required = true
            html.stylesheet = resources.text.fromFile('config/xsl/checkstyle-custom.xsl')
        }
    }

View a sample Checkstyle stylesheet.

## Generate SARIF report

SARIF report is supported on Checkstyle versions 10.3.3 and newer. It is not enabled by default.

Example 4. Enable SARIF Report
build.gradle.kts

    checkstyle {
        toolVersion = "10.3.3"
    }
    tasks.withType<Checkstyle>().configureEach {
        reports {
            sarif.required = true
        }
    }

build.gradle

    checkstyle {
        toolVersion = '10.3.3'
    }
    tasks.withType(Checkstyle) {
        reports {
            sarif.required = true
        }
    }

## 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 Checkstyle.maxHeapSize.

Example 5. Customizing the amount of memory given to Checkstyle
build.gradle.kts

    tasks.withType<Checkstyle>().configureEach {
        minHeapSize = "200m"
        maxHeapSize = "1g"
    }

build.gradle

    tasks.withType(Checkstyle) {
        minHeapSize = "200m"
        maxHeapSize = "1g"
    }