<chapter id="checkstyle_plugin">
    <title>The Checkstyle Plugin</title>
    <para>The Checkstyle plugin performs quality checks on your project's Java source files using <ulink url="http://checkstyle.sourceforge.net/index.html">Checkstyle</ulink>
        and generates reports from these checks.
    </para>

    <section id="sec:checkstyle_usage">
        <title>Usage</title>
        <para>To use the Checkstyle plugin, include the following in your build script:</para>
        <sample id="useCheckstylePlugin" dir="codeQuality" title="Using the Checkstyle plugin">
            <sourcefile file="build.gradle" snippet="use-checkstyle-plugin"/>
        </sample>
        <para>The plugin adds a number of tasks to the project that perform the quality checks. You can execute the checks by running <userinput>gradle check</userinput>.</para>
        <para>Note that Checkstyle will run with the same Java version used to run Gradle.</para>
    </section>
    <section id="sec:checkstyle_tasks">
        <title>Tasks</title>
        <para>The Checkstyle plugin adds the following tasks to the project:</para>
        <table>
            <title>Checkstyle plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>checkstyleMain</literal>
                </td>
                <td><literal>classes</literal></td>
                <td><apilink class="org.gradle.api.plugins.quality.Checkstyle"/></td>
                <td>Runs Checkstyle against the production Java source files.</td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyleTest</literal>
                </td>
                <td><literal>testClasses</literal></td>
                <td><apilink class="org.gradle.api.plugins.quality.Checkstyle"/></td>
                <td>Runs Checkstyle against the test Java source files.</td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyle<replaceable>SourceSet</replaceable></literal>
                </td>
                <td><literal><replaceable>sourceSet</replaceable>Classes</literal></td>
                <td><apilink class="org.gradle.api.plugins.quality.Checkstyle"/></td>
                <td>Runs Checkstyle against the given source set's Java source files.</td>
            </tr>
        </table>

        <para>The Checkstyle plugin adds the following dependencies to tasks defined by the Java plugin.</para>
        <table>
            <title>Checkstyle plugin - additional task dependencies</title>
            <thead>
                <td>Task name</td>
                <td>Depends on</td>
            </thead>
            <tr>
                <td><literal>check</literal></td>
                <td>All Checkstyle tasks, including <literal>checkstyleMain</literal> and <literal>checkstyleTest</literal>.</td>
            </tr>
        </table>
    </section>

    <section id="sec:checkstyle_project_layout">
        <title>Project layout</title>
        <para>By default, the Checkstyle plugin expects the following project layout, but this can be changed:</para>
        <table>
            <title>Checkstyle plugin - project layout</title>
            <thead>
                <tr>
                    <td>File</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>config/checkstyle</filename>
                </td>
                <td>Other Checkstyle configuration files (e.g., <filename>suppressions.xml</filename>)</td>
            </tr>
            <tr>
                <td>
                    <filename>config/checkstyle/checkstyle.xml</filename>
                </td>
                <td>Checkstyle configuration file</td>
            </tr>
        </table>
    </section>

    <section id="sec:checkstyle_dependency_management">
        <title>Dependency management</title>
        <para>The Checkstyle plugin adds the following dependency configurations:</para>
        <table>
            <title>Checkstyle plugin - dependency configurations</title>
            <thead>
                <tr>
                    <td>Name</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>checkstyle</filename>
                </td>
                <td>The Checkstyle libraries to use</td>
            </tr>
        </table>
    </section>

    <section id="sec:checkstyle_configuration">
        <title>Configuration</title>
        <para>See the <apilink class="org.gradle.api.plugins.quality.CheckstyleExtension"/> class in the API documentation.</para>
        <section id="sec:checkstyle_built_in_variables">
            <title>Built-in variables</title>
            <para>
                The Checkstyle plugin defines a <literal>config_loc</literal> property that can be used in Checkstyle configuration files to define paths to other configuration files like <filename>suppressions.xml</filename>.
            </para>
            <sample id="useConfigLoc" dir="codeQuality" title="Using the config_loc property">
                <sourcefile file="config/checkstyle/checkstyle.xml" snippet="use-config-loc"/>
            </sample>
        </section>
    </section>

    <section id="sec:checkstyle_customize_xsl">
        <title>Customizing the HTML report</title>
        <para>The HTML report generated by the <apilink class="org.gradle.api.plugins.quality.Checkstyle"/> task
            can be customized using a XSLT stylesheet, for example to highlight specific errors or change its
            appearance:
        </para>
        <sample id="customizeCheckstyleReport" dir="codeQuality" title="Customizing the HTML report">
            <sourcefile file="build.gradle" snippet="customize-checkstyle-report"/>
        </sample>
        <para>
            <ulink url="https://github.com/checkstyle/contribution/tree/master/xsl">View a sample Checkstyle stylesheet.</ulink>
        </para>
    </section>

</chapter>
