Checkstyle ANT Task - Version 3.1

Description

This task runs Checkstyle over specified Java files. The task has been tested using ANT 1.5. The latest version of checkstyle can be found at http://checkstyle.sourceforge.net/. This task is included in the checkstyle distribution.

Installation

The easiest way is to include checkstyle-all-3.1.jar in the classpath. This contains all the classes required to run Checkstyle. Alternatively, you must include the following in the classpath:

checkstyle-3.1.jar
ANTLR 2.7.1 classes. antlr.jar is included in the distribution.
Jakarta Regexp 1.2 classes. jakarta-regexp-1.2.jar is included in the distribution.
Jakarta Commons Beanutils classes. commons-beanutils.jar is included in the distribution.
Jakarta Commons Collections classes. commons-collections.jar is included in the distribution.
Jakarta Commons Logging classes. commons-logging.jar is included in the distribution.
A JAXP compliant XML parser implementation. You already have it on your system if you run ANT or JDK 1.4.

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

  <taskdef resource="checkstyletask.properties"
           classpath="/path/to/checkstyle-all-3.1.jar"/>

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

  <taskdef resource="checkstyletask.properties"/>

Parameters

Attribute	Description	Required
file	File to run checkstyle on.	One of either file or at least one nested fileset element
config	Specifies a file that defines the configuration modules. See here for a description of how to define a configuration.	Exactly one of config or configURL
configURL	Specifies a URL that defines the configuration modules. See here for a description of how to define a configuration.	Exactly one of config or configURL
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
packageNamesFile	Specifies a file that contains package names for the configuration.	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
classpath	The classpath to use when looking up classes. Defaults to the current classpath.	No

Nested Elements

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

The parameters for the <formatter> element are:

type

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

plain - specifies the DefaultLogger
xml - specifies the XMLLogger

Defaults to "plain".

toFile

The file to write output to. Defaults to standard output. Note, there is no way to explicitly specify standard output.

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

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

  <checkstyle config="docs/checkstyle_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/checkstyle_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 set of files and output messages to standard output in plain format, and a file in XML format

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

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

  <checkstyle config="docs/checkstyle_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/checkstyle_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>