Checkstyle ANT Task - Version 2.4

Description

This task runs Checkstyle over specified Java files. The task has been tested using ANT 1.4.1. 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-2.4.jar in the classpath. This contains all the classes required to run Checkstyle. Alternatively, you must include the following in the classpath:

checkstyle-2.4.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.

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

  <taskdef name="checkstyle"
           classname="com.puppycrawl.tools.checkstyle.CheckStyleTask"/>

Alternatively, since checkstyle version 2.2 you can use taskdef's resource attribute:

  <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
properties	Specifies a properties file that contains the configuration options. See here for all available configuration options. Use the nested <property> element to override properties in the file. This is very useful with project specific properties like reporting 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.

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 on a single file

  <checkstyle file="Check.java"/>

Run checkstyle on a set of Java files using Site-wide Checkstyle rules and overriding properties

  <checkstyle properties="/path/to/site/checkstyle.rules">
    <fileset dir="src/checkstyle" includes="**/*.java"/>

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

    <!-- This project allows tabs (big mistake:-) -->
    <property key="checkstyle.allow.tabs" value="true"/>
  </checkstyle>

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

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

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