277 lines
10 KiB
HTML
277 lines
10 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<title>Checkstyle ANT Task - Version @CHECKSTYLE_VERSION@</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css"/>
|
|
</head>
|
|
|
|
<body>
|
|
<h1><a name="checkstyle">Checkstyle ANT Task - Version @CHECKSTYLE_VERSION@</a></h1>
|
|
<h3>Description</h3>
|
|
|
|
<p>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 <a href="http://checkstyle.sourceforge.net/">http://checkstyle.sourceforge.net/</a>.
|
|
This task is included in the checkstyle distribution.</p>
|
|
|
|
<h3>Installation</h3>
|
|
<p>The easiest way is to include <span class="default">checkstyle-all-@CHECKSTYLE_VERSION@.jar</span> in the classpath. This contains all the classes required to run Checkstyle. Alternatively, you must include the following in the classpath:</p>
|
|
<ol>
|
|
<li><span class="default">checkstyle-@CHECKSTYLE_VERSION@.jar</span></li>
|
|
<li>ANTLR 2.7.2 classes. <span class="default">antlr.jar</span> is included in the distribution.</li>
|
|
<li>Jakarta Regexp 1.3 classes. <span class="default">jakarta-regexp-1.3.jar</span> is included in the distribution.</li>
|
|
<li>Jakarta Commons Beanutils classes. <span class="default">commons-beanutils.jar</span> is included in the distribution.</li>
|
|
<li>Jakarta Commons Collections classes. <span class="default">commons-collections.jar</span> is included in the distribution.</li>
|
|
<li>Jakarta Commons Logging classes. <span class="default">commons-logging.jar</span> is included in the distribution.</li>
|
|
<li>A JAXP compliant XML parser implementation. You already have it on your system if you run ANT or JDK 1.4.</li>
|
|
</ol>
|
|
|
|
<p>To use the task in a build file, you will need the following
|
|
<code>taskdef</code> declaration:</p>
|
|
|
|
<pre>
|
|
<taskdef resource="checkstyletask.properties"
|
|
classpath="/path/to/checkstyle-all-@CHECKSTYLE_VERSION@.jar"/>
|
|
</pre>
|
|
|
|
|
|
<p>Or, assuming that Checkstyle is in the global classpath (not recommended),
|
|
then you will need the following <code>taskdef</code> declaration:</p>
|
|
|
|
<pre>
|
|
<taskdef resource="checkstyletask.properties"/>
|
|
</pre>
|
|
|
|
|
|
<h3>Parameters</h3>
|
|
<table border="1" cellpadding="2" cellspacing="0" summary="parameters">
|
|
<tr class="header">
|
|
<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 class="required">One of either <i>file</i> or at least one nested <i>fileset</i> element</td>
|
|
</tr>
|
|
<tr>
|
|
<td>config</td>
|
|
<td>Specifies a file that defines the configuration modules.
|
|
<a href="config.html">See here</a> for a description of how to define a configuration.</td>
|
|
<td class="required">Exactly one of config or configURL</td>
|
|
</tr>
|
|
<tr>
|
|
<td>configURL</td>
|
|
<td>Specifies a URL that defines the configuration modules.
|
|
<a href="config.html">See here</a> for a description of how to define a configuration.</td>
|
|
<td class="required">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 class="required">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>packageNamesFile</td>
|
|
<td>
|
|
Specifies a file that contains <a href="config.html#packagenames">
|
|
package names</a> for the configuration.
|
|
</td>
|
|
<td class="required">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>failOnViolation</td>
|
|
<td>Specifies whether the build will continue even if there are violations.
|
|
Defaults to <span class="default">"true"</span>.</td>
|
|
<td class="required">No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>failureProperty</td>
|
|
<td>The name of a property to set in the event of a violation.</td>
|
|
<td class="required">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
|
|
<span class="default">"0"</span>.</td>
|
|
<td class="required">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
|
|
<span class="default">"2147483647"</span>, i.e.
|
|
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Integer.html#MAX_VALUE">Integer.MAX_VALUE</a>.</td>
|
|
<td class="required">No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>classpath</td>
|
|
<td>The classpath to use when looking up classes. Defaults to the current classpath.</td>
|
|
<td class="required">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 class="required">No</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
<h3>Nested Elements</h3>
|
|
|
|
<p>This task supports the nested elements
|
|
<a href="http://ant.apache.org/manual/CoreTypes/fileset.html"><fileset></a>,
|
|
<a href="http://ant.apache.org/manual/using.html#path"><classpath></a>,
|
|
<span class="default"><formatter></span>, and
|
|
<span class="default"><property></span>.</p>
|
|
|
|
<p>The parameters for the <span class="default"><formatter></span> element are:</p>
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0" summary="nested elements">
|
|
<tr class="header">
|
|
<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><span class="default">plain</span> - specifies the <a href="api/com/puppycrawl/tools/checkstyle/DefaultLogger.html">DefaultLogger</a></li>
|
|
<li><span class="default">xml</span> - specifies the <a href="api/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a></li>
|
|
</ul>
|
|
<p>Defaults to <span class="default">"plain"</span>.</p>
|
|
</td>
|
|
<td class="required">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 class="required">No</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<p>A <span class="default"><property></span> element provides a property for
|
|
<a href="config.html#properties">expanded property values</a> of the configuration.
|
|
The parameters for the <span class="default"><property></span> element are:</p>
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0" summary="nested elements">
|
|
<tr class="header">
|
|
<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 class="required">Yes</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>value</td>
|
|
<td>The value of the property specified as a string.</td>
|
|
<td class="required">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 class="required">Either <i>value</i> or <i>file</i></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Examples</h3>
|
|
<p><b>Run checkstyle with configuration file <code>docs/sun_checks.xml</code> on a single file</b></p>
|
|
<pre>
|
|
<checkstyle config="docs/sun_checks.xml" file="Check.java"/>
|
|
</pre>
|
|
|
|
<p><b>Run checkstyle on a set of Java files using site-wide configuration and
|
|
an expanded property value</b></p>
|
|
<pre>
|
|
<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>
|
|
</pre>
|
|
|
|
<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>
|
|
<pre>
|
|
<checkstyle config="docs/sun_checks.xml">
|
|
<fileset dir="src/checkstyle" includes="**/*.java"/>
|
|
<formatter type="plain"/>
|
|
<formatter type="xml" toFile="build/checkstyle_errors.xml"/>
|
|
</checkstyle>
|
|
</pre>
|
|
<p>
|
|
<b>Run checkstyle with configuration file <code>docs/sun_checks.xml</code> on a file and
|
|
provide a package names file</b>
|
|
</p>
|
|
<pre>
|
|
<checkstyle config="docs/sun_checks.xml"
|
|
packageNamesFile="myPackageNames.xml"
|
|
file="Check.java"/>
|
|
</pre>
|
|
|
|
<p>
|
|
|
|
<p><b>Run checkstyle in an automated build and send an email report if style violations are detected</b></p>
|
|
<pre>
|
|
<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>
|
|
</pre>
|
|
|
|
<hr />
|
|
<p class="copyright">Copyright © 2002-2004 Oliver Burn. All rights Reserved.</p>
|
|
</body>
|
|
</html>
|