Content

Description

This task runs Checkstyle over specified Java files. The latest version of checkstyle can be found at https://checkstyle.org/. This task is included in the checkstyle distribution.

Installation

The easiest way is to include checkstyle-10.20.1-all.jar in the classpath. This contains all the classes required to run Checkstyle. Alternatively, you must include the compile third party dependencies listed in Project Dependencies in the classpath.

To use the task in a build file, you will need the following taskdef declaration: 

<taskdef resource="com/puppycrawl/tools/checkstyle/ant/checkstyle-ant-task.properties"
         classpath="/path/to/checkstyle-10.20.1-all.jar"/>

Or, assuming that Checkstyle is in the global classpath (not recommended), then you will need the following taskdef declaration: 

<taskdef
  resource="com/puppycrawl/tools/checkstyle/ant/checkstyle-ant-task.properties"/>

Or if you use Ant 1.6 and later and assuming that Checkstyle is in the library search path, then you may use antlib feature of Ant (see https://ant.apache.org/manual/Types/antlib.html for more details). For example: 

<project name="foo" ...
         xmlns:cs="antlib:com.puppycrawl.tools.checkstyle.ant">
...
  <cs:checkstyle>
  ...
  </cs:checkstyle>
...
</project>

Parameters

Attribute Description Required
file File to run checkstyle on. One of either file or at least one nested fileset or path element
fileset A set of files to run checkstyle on. Nested attribute. See fileset ant documentation for details One of either file or at least one nested fileset or path element
path A set of path to run checkstyle on. Nested attribute. See path ant documentation for details One of either file or at least one nested fileset or path element
config Specifies the location of the file, URL, or Java resource that defines the configuration modules.
See here for a description of how to define a configuration. 		Exactly one config location
properties Specifies a file that contains properties for expanded property values of the configuration. Ant properties (like ${basedir}) and nested property elements override the properties in this file. No
failOnViolation Specifies whether the build will continue even if there are violations. Defaults to "true". No
failureProperty The name of a property to set in the event of a violation. No
maxErrors The maximum number of errors that are tolerated before breaking the build or setting the failure property. Defaults to "0". No
maxWarnings The maximum number of warnings that are tolerated before breaking the build or setting the failure property. Defaults to "2147483647", i.e. Integer.MAX_VALUE. No
executeIgnoredModules For efficiency, Checkstyle does not invoke modules with a configured severity of "ignore" (since their output would be ignored anyway). A small number of modules may choose to log above their configured severity level and so always need to be invoked. These settings specify that behaviour. Defaults to "false". No

Note that the packageNamesFile parameter has been dropped for Checkstyle 5.0, because of significant changes regarding package name file handling. See for details.

Also note, that checkstyle ignores all duplicate files, specified in the file, fileset or path parameters

Nested Elements

This task supports the nested elements <fileset>, <classpath>, <path>, <formatter>, and <property>.

The parameters for the <formatter> element are:

Attribute Description Required
type

The type of output to generate. The valid values are:

Defaults to "plain".

 No
toFile The file to write output to. Defaults to standard output. Note, there is no way to explicitly specify standard output. No
useFile Boolean that determines whether output should be sent to a file. Default is true. No

A <property> element provides a property for expanded property values of the configuration. The parameters for the <property> element are:

Attribute Description Required
key

The key for the property.

 Yes
value The value of the property specified as a string. Either value or file
file The value of the property specified as a file. This is great for specifying file names relative to the ANT build file. Either value or file

Examples

An example project can be found here.

Checkstyle use ant configuration to validate its own code. See example is our git repository - config/ant-phase-verify.xml.

Run checkstyle with configuration file docs/sun_checks.xml on a single file 

<checkstyle config="docs/sun_checks.xml" file="Check.java"/>

Run checkstyle on a set of Java files using site-wide configuration and an expanded property value 

<checkstyle config="/path/to/site/sun_checks.xml">
  <fileset dir="src/checkstyle" includes="**/*.java"/>

  <!-- Location of cache-file. Something that is project specific -->
  <property key="checkstyle.cache.file" file="target/cachefile"/>
</checkstyle>

Run checkstyle on a previously defined source path. 

<!-- Somewhere in your config -->
<path id="project.sourcepath">
  <fileset dir="src"
          includes="**/*"
          excludes="it/resources/**/*,test/resources/**/*,test/resources-noncompilable/**/*"/>
</path>

<!-- Actual checkstyle config -->
<checkstyle config="/path/to/site/sun_checks.xml">
  <!-- Refer to a previously defined source path -->
  <path refid="project.sourcepath" />
</checkstyle>

Run checkstyle on a set of files and output messages to standard output in plain format, and files in XML & SARIF format 

<checkstyle config="docs/sun_checks.xml">
  <fileset dir="src/checkstyle" includes="**/*.java"/>
  <formatter type="plain"/>
  <formatter type="xml" toFile="build/checkstyle_errors.xml"/>
  <formatter type="sarif" toFile="build/checkstyle_errors.sarif"/>
</checkstyle>

Run checkstyle with configuration file docs/sun_checks.xml on a file and provide a package names file 

<checkstyle config="docs/sun_checks.xml"
            packageNamesFile="myPackageNames.xml"
            file="Check.java"/>

Run checkstyle in an automated build and send an email report if style violations are detected 

<target name="checkstyle"
        description="Generates a report of code convention violations.">

  <checkstyle config="docs/sun_checks.xml"
              failureProperty="checkstyle.failure"
              failOnViolation="false">
    <formatter type="xml" tofile="checkstyle_report.xml"/>
    <fileset dir="src" includes="**/*.java"/>
  </checkstyle>

  <style in="checkstyle_report.xml" out="checkstyle_report.html"
      style="checkstyle.xsl"/>

</target>

<!-- run this target as part of automated build -->
<target name="checkstyle-nightly"
        depends="checkstyle"
        if="checkstyle.failure"
        description="Sends email if checkstyle detected code conventions violations.">

  <!-- use your own server and email addresses below. See Ant documentation for details -->

  <mail from="qa@some.domain"
        tolist="someone@some.domain,someoneelse@some.domain"
        mailhost="mailbox.some.domain"
        subject="Checkstyle violation(s) in project ${ant.project.name}"
        files="checkstyle_report.html"/>

</target>

To run checkstyle with a custom JAR with implementation of custom Checks be sure the custom JAR is found on the classpath. An example can be found at checkstyle-samples.