392 lines
20 KiB
HTML
392 lines
20 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
|
<html>
|
|
<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.4.1. 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.1 classes. <span class="default">antlr.jar</span> is included in the distribution.</li>
|
|
<li>Jakarta Regexp 1.2 classes. <span class="default">jakarta-regexp-1.2.jar</span> is included in the distribution.</li>
|
|
</ol>
|
|
|
|
<p>To use the task in a build file, you will need the following <code>taskdef</code> declaration:</p>
|
|
<pre>
|
|
<taskdef name="checkstyle"
|
|
classname="com.puppycrawl.tools.checkstyle.CheckStyleTask"/>
|
|
</pre>
|
|
<p>Alternatively, since checkstyle version 2.2 you can use <code>taskdef</code>'s resource attribute:</p>
|
|
<pre>
|
|
<taskdef resource="checkstyletask.properties"/>
|
|
</pre>
|
|
|
|
|
|
<h3>Parameters</h3>
|
|
<table border="1" cellpadding="2" cellspacing="0" summary="parameters">
|
|
<tr class="header">
|
|
<td valign="top"><b>Attribute</b></td>
|
|
<td valign="top"><b>Description</b></td>
|
|
<td valign="top"><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">file</td>
|
|
<td valign="top">File to run checkstyle on.</td>
|
|
<td align="center" valign="top">One of either <i>file</i> or at least one nested <i>fileset</i> element</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">properties</td>
|
|
<td valign="top">Specifies a properties file that contains the configuration options. This is useful for sharing checkstyle configurations across ant build files. The property names to use in the file are the same as on the <a href="cmdline.html">command line</a>. Other parameters to the ANT task override the settings in the properties file.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">lcurlyType</td>
|
|
<td valign="top">Specifies the policy of where to put the left brace <span class=code>'{'</span> for type declarations. The legal values are defined <a href="engine.html#lcurlyopt">here</a>. Defaults to <span class="default">"eol"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">lcurlyMethod</td>
|
|
<td valign="top">Specifies the policy of where to put the left brace <span class=code>'{'</span> for method declarations. The legal values are defined <a href="engine.html#lcurlyopt">here</a>. Defaults to <span class="default">"eol"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">lcurlyOther</td>
|
|
<td valign="top">Specifies the policy of where to put the left brace <span class=code>'{'</span> for other declarations. The keywords covered is defined <a href="engine.html#lcurlyother">here</a>. The legal values are defined <a href="engine.html#lcurlyopt">here</a>. Defaults to <span class="default">"eol"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">rcurly</td>
|
|
<td valign="top">Specifies the policy of where to put the right brace <span class=code>'}'</span>. The keywords covered is defined <a href="engine.html#rcurly">here</a>. The legal values are defined <a href="engine.html#rcurlyopt">here</a>. Defaults to <span class="default">"same"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">parenPad</td>
|
|
<td valign="top">Specifies the policy of how to pad parenthesises. The legal values are defined <a href="engine.html#parenpad">here</a>. Defaults to <span class="default">"nospace"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">tryBlock</td>
|
|
<td valign="top">Specifies the policy of how check <span class="code">try</span> blocks. The legal values are defined <a href="engine.html#blockOpt">here</a>. Defaults to <span class="default">"stmt"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">catchBlock</td>
|
|
<td valign="top">Specifies the policy of how check <span class="code">catch</span> blocks. The legal values are defined <a href="engine.html#blockOpt">here</a>. Defaults to <span class="default">"text"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">finallyBlock</td>
|
|
<td valign="top">Specifies the policy of how check <span class="code">finally</span> blocks. The legal values are defined <a href="engine.html#blockOpt">here</a>. Defaults to <span class="default">"stmt"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">allowTabs</td>
|
|
<td valign="top">Indicates whether to allow tabs. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">allowProtected</td>
|
|
<td valign="top">Indicates whether to allow protected data. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">allowPackage</td>
|
|
<td valign="top">Indicates whether to allow package visible data. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">allowNoAuthor</td>
|
|
<td valign="top">Indicates whether to allow no <span class="default">@author</span> tag to be defined for class and interface Javadoc comments. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">maxLineLen</td>
|
|
<td valign="top">Specifies the maximum line length. Default value is defined <a href="engine.html#length">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">tabWidth</td>
|
|
<td valign="top">The distance between tab stops, used in line number and column calculations. Default value is <span class="default">"8"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreLineLengthPattern</td>
|
|
<td valign="top">Specifies a regular expression for lines to ignore in maximum line length checks. Defaults to <span class="default">"^$"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreImportLen</td>
|
|
<td valign="top">Specifies whether to ignore the maximum line length for <span class="code">import</span> statements. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">maxMethodLen</td>
|
|
<td valign="top">Specifies the maximum method length. Default value is defined <a href="engine.html#methodLength">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">maxConstructorLen</td>
|
|
<td valign="top">Specifies the maximum constructor length. Default value is defined <a href="engine.html#constructorLength">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">maxFileLen</td>
|
|
<td valign="top">Specifies the maximum file length. Default value is defined <a href="engine.html#fileLength">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">todoPattern</td>
|
|
<td valign="top">Specifies the regular expression to match for to-do comments. Default value is defined <a href="engine.html#todo">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">memberPattern</td>
|
|
<td valign="top">Specifies the regular expression to match against member variables. Default value is defined <a href="engine.html#varformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">publicMemberPattern</td>
|
|
<td valign="top">Specifies the regular expression to match against public member variables. Default value is defined <a href="engine.html#fieldformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">paramPattern</td>
|
|
<td valign="top">Specifies the regular expression to match against parameters. Default value is defined <a href="engine.html#paramformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">constPattern</td>
|
|
<td valign="top">Specifies the regular expression to match against static/final variables. Default value is defined <a href="engine.html#varformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">staticPattern</td>
|
|
<td valign="top">Specifies the regular expression to match against static variables. Default value is defined <a href="engine.html#varformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">typePattern</td>
|
|
<td valign="top">Specifies the regular expression to match against type names. Default value is defined <a href="engine.html#typeformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">methodPattern</td>
|
|
<td valign="top">Specifies the regular expression to match against method names. Default value is defined <a href="engine.html#methodformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">localVarPattern</td>
|
|
<td valign="top">Specifies the regular expression to match against local variable names. Default value is defined <a href="engine.html#localvarformat">here</a>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">headerFile</td>
|
|
<td valign="top">Specifies the file containing the header lines. Default is to not check.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">headerLinesRegexp</td>
|
|
<td valign="top">Specifies whether to interpret each line in the headerFile as a regular expression. Default is <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">headerIgnoreLine</td>
|
|
<td valign="top">Specifies a comma separated list of the lines in the header to ignore when comparing. Default is to not ignore any line.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">javadocScope</td>
|
|
<td valign="top">Specifies the visibility scope where javadoc comments are checked. Valid values are <span class="default">"nothing"</span>, <span class="default">"public"</span>, <span class="default">"protected"</span>, <span class="default">"package"</span>, <span class="default">"private"</span> and <span class="default">"anoninner"</span>. Defaults to <span class="default">"private"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">requirePackageHtml</td>
|
|
<td valign="top">Specifies whether to require that package documentation is available. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreImports</td>
|
|
<td valign="top">Specifies whether to ignore checking import statements. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">illegalImports</td>
|
|
<td valign="top">Comma separated list of package prefixes that are not allowed in import statements. Defaults to <span class="default">"sun"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">illegalInstantiations</td>
|
|
<td valign="top">Comma separated list of fully qualified class names that are not allowed to be instantiated. Defaults to <span class="default">""</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreWhitespace</td>
|
|
<td valign="top">Specifies whether to ignore checking whitespace. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreCastWhitespace</td>
|
|
<td valign="top">Specifies whether to ignore checking for whitespace after a cast. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreOpWrap</td>
|
|
<td valign="top">Specifies whether to ignore checking wrapping on operators. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreBraces</td>
|
|
<td valign="top">Specifies whether to ignore checking braces. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignoreLongEll</td>
|
|
<td valign="top">Specifies whether to ignore checking the <span class="code">L</span> in long integer literals. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">ignorePublicInInterface</td>
|
|
<td valign="top">Specifies whether to ignore the public keyword in interface definitions. Defaults to <span class="default">"false"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">failOnViolation</td>
|
|
<td valign="top">Specifies whether the build will continue even if there are violations. Defaults to <span class="default">"true"</span>.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">failureProperty</td>
|
|
<td valign="top">The name of a property to set in the event of a violation.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">cacheFile</td>
|
|
<td valign="top">Specifies the name of a file that can be used to cache details of files that pass checkstyle. This can signicantly increase the speed of checkstyle on successive runs.</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Older versions of the checkstyle task supported the boolean parameters <span class="default">relaxJavadoc</span> and <span class="default">ignoreJavadoc</span>. These parameters have been removed because they were conflicting and the semantics of <span class="default">relaxJavadoc</span> was not clearly specified. The two parameters have been replaced by the <span class="default">javadocScope</span> parameter. Instead of <span class="default">ignoreJavadoc="true"</span> you can now use <span class="default">javadocScope="nothing"</span>. The behaviour of <span class="default">relaxJavadoc="true"</span> is roughly the same as <span class="default">javadocScope="protected"</span>.</p>
|
|
|
|
<h3>Nested Elements</h3>
|
|
|
|
<p>This task supports the nested elements <a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html"><fileset></a> and <span class="default"><formatter></span>. 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 valign="top"><b>Attribute</b></td>
|
|
<td valign="top"><b>Description</b></td>
|
|
<td valign="top"><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">type</td>
|
|
<td valign="top">
|
|
<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 align="center" valign="top">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">toFile</td>
|
|
<td valign="top">The file to write output to. Defaults to standard output. Note, there is no way to explicitly specify standard output.
|
|
</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h3>Examples</h3>
|
|
<p><b>Run checkstyle on a single file</b></p>
|
|
<pre>
|
|
<checkstyle file="Check.java"/>
|
|
</pre>
|
|
|
|
<p><b>Run checkstyle on a set of Java files in directory</b></p>
|
|
<pre>
|
|
<checkstyle>
|
|
<fileset dir="src/checkstyle" includes="**/*.java"/>
|
|
</checkstyle>
|
|
</pre>
|
|
|
|
<p><b>Run checkstyle on a set of Java files and allow tabs</b></p>
|
|
<pre>
|
|
<checkstyle allowTabs="yes">
|
|
<fileset dir="src/checkstyle" includes="**/*.java"/>
|
|
</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>
|
|
<fileset dir="src/checkstyle" includes="**/*.java"/>
|
|
<formatter type="plain"/>
|
|
<formatter type="xml" toFile="build/checkstyle_errors.xml"/>
|
|
</checkstyle>
|
|
</pre>
|
|
|
|
<p><b>Run checkstyle on a set of Java files and disable pattern matching</b></p>
|
|
<pre>
|
|
<checkstyle allowTabs="yes"
|
|
paramPattern="."
|
|
constPattern="."
|
|
staticPattern="."
|
|
memberPattern=".">
|
|
<fileset dir="src/checkstyle" includes="**/*.java"/>
|
|
</checkstyle>
|
|
</pre>
|
|
|
|
<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 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 align="center">Copyright © 2001 Oliver Burn. All rights Reserved.</p>
|
|
</body>
|
|
</html>
|