421 lines
13 KiB
XML
421 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<document xmlns="http://maven.apache.org/XDOC/2.0"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
|
|
|
|
<head>
|
|
<title>Ant Task</title>
|
|
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/>
|
|
<script type="text/javascript" src="js/anchors.js"/>
|
|
<script type="text/javascript" src="js/google-analytics.js"/>
|
|
<link rel="icon" href="images/favicon.png" type="image/x-icon" />
|
|
<link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
|
|
</head>
|
|
|
|
<body>
|
|
<section name="Content">
|
|
<macro name="toc">
|
|
<param name="fromDepth" value="1"/>
|
|
<param name="toDepth" value="1"/>
|
|
</macro>
|
|
</section>
|
|
|
|
<section name="Description">
|
|
|
|
<p>
|
|
This task runs Checkstyle over specified Java files.
|
|
The latest version of checkstyle can be found at
|
|
<a href="http://checkstyle.sourceforge.net/">http://checkstyle.sourceforge.net/</a>.
|
|
|
|
This task is included in the checkstyle distribution.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section name="Installation">
|
|
|
|
<p>
|
|
The easiest way is to include
|
|
<code>checkstyle-${projectVersion}-all.jar</code> in the
|
|
classpath. This contains all the classes required to run
|
|
Checkstyle. Alternatively, you must include the
|
|
<code>compile</code> third party dependencies listed in <a
|
|
href="dependencies.html">Project Dependencies</a> in the
|
|
classpath.
|
|
</p>
|
|
|
|
<p>
|
|
To use the task in a build file, you will need the following
|
|
<code>taskdef</code> declaration:
|
|
</p>
|
|
|
|
<source>
|
|
<taskdef resource="com/puppycrawl/tools/checkstyle/ant/checkstyle-ant-task.properties"
|
|
classpath="/path/to/checkstyle-${projectVersion}-all.jar"/>
|
|
</source>
|
|
|
|
<p>
|
|
Or, assuming that Checkstyle is in the global classpath (not
|
|
recommended), then you will need the following <code>taskdef</code>
|
|
declaration:
|
|
</p>
|
|
|
|
<source>
|
|
<taskdef resource="com/puppycrawl/tools/checkstyle/ant/checkstyle-ant-task.properties"/>
|
|
</source>
|
|
|
|
<p>
|
|
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 <a
|
|
href="http://ant.apache.org/manual/Types/antlib.html"
|
|
>http://ant.apache.org/manual/Types/antlib.html</a>
|
|
for more details). For example:
|
|
</p>
|
|
|
|
<source>
|
|
<project name="foo" ...
|
|
xmlns:cs="antlib:com.puppycrawl.tools.checkstyle.ant">
|
|
...
|
|
<cs:checkstyle>
|
|
...
|
|
</cs:checkstyle>
|
|
...
|
|
</project>
|
|
</source>
|
|
|
|
</section>
|
|
|
|
<section name="Parameters">
|
|
|
|
<table summary="parameters">
|
|
|
|
<tr>
|
|
<td><b>Attribute</b></td>
|
|
<td><b>Description</b></td>
|
|
<td><b>Required</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>file</td>
|
|
<td>File to run checkstyle on.</td>
|
|
<td>
|
|
One of either <i>file</i> or at least one nested <i>fileset</i>
|
|
element
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>config</td>
|
|
<td>
|
|
Specifies the location of the file that defines the configuration
|
|
modules.
|
|
<br/>
|
|
<a href="config.html">See here</a> for a description of how to
|
|
define a configuration.
|
|
</td>
|
|
<td>Exactly one config file</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>configURL</td>
|
|
<td>
|
|
Specifies a URL or name passed to the ClassLoader.getResource() method that defines the configuration modules. <a
|
|
href="config.html">See here</a> for a description of how to define
|
|
a configuration.
|
|
</td>
|
|
<td>Exactly one of config or configURL</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>properties</td>
|
|
<td>
|
|
Specifies a file that contains properties for <a
|
|
href="config.html#Properties"> expanded property values</a> of the
|
|
configuration. Ant properties (like ${basedir}) and nested
|
|
property elements override the properties in this file.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>failOnViolation</td>
|
|
<td>
|
|
Specifies whether the build will continue even if there are
|
|
violations. Defaults to <code>"true"</code>.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>failureProperty</td>
|
|
<td>The name of a property to set in the event of a violation.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>maxErrors</td>
|
|
<td>
|
|
The maximum number of errors that are tolerated before
|
|
breaking the build or setting the failure property. Defaults
|
|
to <code>"0"</code>.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>maxWarnings</td>
|
|
<td>
|
|
The maximum number of warnings that are tolerated before
|
|
breaking the build or setting the failure property. Defaults
|
|
to <code>"2147483647"</code>, i.e.
|
|
|
|
<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html#MAX_VALUE">Integer.MAX_VALUE</a>.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>classpath</td>
|
|
<td>
|
|
The classpath to use when looking up classes. Defaults to the
|
|
current classpath.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>classpathref</td>
|
|
<td>
|
|
The classpath to use when looking up classes, given as a reference
|
|
to a path defined elsewhere.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>omitIgnoredModules</td>
|
|
<td>
|
|
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. This settings specifies that behaviour.
|
|
Defaults to <code>"true"</code>.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
Note that the <code>packageNamesFile</code>
|
|
parameter has been dropped for Checkstyle 5.0, because of
|
|
significant changes regarding package name file handling. See <a
|
|
href="config.html#Packages"/> for details.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Nested Elements">
|
|
|
|
<p>
|
|
This task supports the nested elements <a
|
|
href="http://ant.apache.org/manual/Types/fileset.html"><fileset></a>,
|
|
<a
|
|
href="http://ant.apache.org/manual/using.html#path"><classpath></a>,
|
|
<code><formatter></code>, and <code><property></code>.
|
|
</p>
|
|
|
|
<p>
|
|
The parameters for the <code><formatter></code>
|
|
element are:
|
|
</p>
|
|
|
|
<table summary="nested elements">
|
|
<tr>
|
|
<td><b>Attribute</b></td>
|
|
<td><b>Description</b></td>
|
|
<td><b>Required</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>type</td>
|
|
<td>
|
|
<p>The type of output to generate. The valid values are:</p>
|
|
<ul>
|
|
<li>
|
|
<code>plain</code> - specifies the <a
|
|
href="apidocs/com/puppycrawl/tools/checkstyle/DefaultLogger.html">DefaultLogger</a>
|
|
</li>
|
|
<li>
|
|
<code>xml</code> - specifies the <a
|
|
href="apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a>
|
|
</li>
|
|
</ul>
|
|
<p>Defaults to <code>"plain"</code>.</p>
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>toFile</td>
|
|
<td>
|
|
The file to write output to. Defaults to standard output. Note,
|
|
there is no way to explicitly specify standard output.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>useFile</td>
|
|
<td>Boolean that determines whether output should be sent to
|
|
a file. Default is <code>true</code>.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
A <code><property></code> element provides a property for
|
|
<a href="config.html#Properties">expanded property values</a> of
|
|
the configuration. The parameters for the
|
|
<code><property></code> element are:
|
|
</p>
|
|
|
|
<table summary="nested elements">
|
|
<tr>
|
|
<td><b>Attribute</b></td>
|
|
<td><b>Description</b></td>
|
|
<td><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>key</td>
|
|
<td><p>The key for the property.</p></td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>value</td>
|
|
<td>The value of the property specified as a string.</td>
|
|
<td>Either <i>value</i> or <i>file</i></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>file</td>
|
|
<td>
|
|
The value of the property specified as a file. This is great for
|
|
specifying file names relative to the ANT build file.
|
|
</td>
|
|
<td>Either <i>value</i> or <i>file</i></td>
|
|
</tr>
|
|
</table>
|
|
|
|
</section>
|
|
|
|
<section name="Examples">
|
|
|
|
<p>
|
|
An example project can be found
|
|
<a href="https://github.com/sevntu-checkstyle/checkstyle-samples/tree/master/ant-project">here</a>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>
|
|
Checkstyle use ant configuration to validate its own code. See example is our git repository -
|
|
<a href="https://github.com/checkstyle/checkstyle/blob/master/config/ant-phase-verify.xml#L25">
|
|
config/ant-phase-verify.xml</a>.
|
|
</b>
|
|
</p>
|
|
|
|
<p>
|
|
<b>
|
|
Run checkstyle with configuration file
|
|
<code>docs/sun_checks.xml</code> on a single file
|
|
</b>
|
|
</p>
|
|
|
|
<source>
|
|
<checkstyle config="docs/sun_checks.xml" file="Check.java"/>
|
|
</source>
|
|
|
|
<p>
|
|
<b>
|
|
Run checkstyle on a set of Java files using site-wide configuration
|
|
and an expanded property value
|
|
</b>
|
|
</p>
|
|
<source>
|
|
<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>
|
|
</source>
|
|
|
|
<p>
|
|
<b>
|
|
Run checkstyle on a set of files and output messages to standard
|
|
output in plain format, and a file in XML format
|
|
</b>
|
|
</p>
|
|
<source>
|
|
<checkstyle config="docs/sun_checks.xml">
|
|
<fileset dir="src/checkstyle" includes="**/*.java"/>
|
|
<formatter type="plain"/>
|
|
<formatter type="xml" toFile="build/checkstyle_errors.xml"/>
|
|
</checkstyle>
|
|
</source>
|
|
|
|
<p>
|
|
<b>
|
|
Run checkstyle with configuration file
|
|
<code>docs/sun_checks.xml</code> on a file and provide a package
|
|
names file
|
|
</b>
|
|
</p>
|
|
<source>
|
|
<checkstyle config="docs/sun_checks.xml"
|
|
packageNamesFile="myPackageNames.xml"
|
|
file="Check.java"/>
|
|
</source>
|
|
|
|
<p>
|
|
<b>
|
|
Run checkstyle in an automated build and send an email report if
|
|
style violations are detected
|
|
</b>
|
|
</p>
|
|
<source>
|
|
<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>
|
|
</source>
|
|
|
|
</section>
|
|
</body>
|
|
</document>
|
|
|