558 lines
24 KiB
HTML
558 lines
24 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 Configuration</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css"/>
|
|
</head>
|
|
|
|
<body>
|
|
<!-- The header -->
|
|
<table border="0" width="100%" summary="header layout">
|
|
<tr>
|
|
<td><h1>Checkstyle Configuration</h1></td>
|
|
<td align="right"><img src="logo.png" alt="Checkstyle Logo"/></td>
|
|
</tr>
|
|
</table>
|
|
<!-- content -->
|
|
<table border="0" width="100%" cellpadding="5" summary="body layout">
|
|
<tr>
|
|
<!--Left menu-->
|
|
<td class="menu" valign="top">
|
|
<ul>
|
|
<li>
|
|
<a href="#overview">Overview</a>
|
|
</li>
|
|
<li>
|
|
<a href="#modules">Modules</a>
|
|
</li>
|
|
<li>
|
|
<a href="#properties">Properties</a>
|
|
</li>
|
|
<li>
|
|
<a href="#checker">Checker</a>
|
|
</li>
|
|
<li>
|
|
<a href="#treewalker">TreeWalker</a>
|
|
</li>
|
|
<li>
|
|
<a href="#treewalkerchecks">TreeWalker Checks</a>
|
|
</li>
|
|
<li>
|
|
<a href="#packagenames">Packages</a>
|
|
</li>
|
|
<li>
|
|
<a href="#xml">XML Details</a>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<!--Content-->
|
|
<td class="content" valign="top" align="left">
|
|
|
|
<a name="overview"></a> <h2>Overview</h2>
|
|
<p class="body">
|
|
A Checkstyle configuration specifies which <em>modules</em> to plug in and apply to Java
|
|
source files. Modules are structured in a tree whose root is the <em>Checker</em>
|
|
module. The next level of modules contains <em>FileSetChecks</em>- modules that
|
|
take a set of input files and fire error messages. Many checks are submodules of
|
|
the <em>TreeWalker</em> FileSetCheck module. The TreeWalker operates by
|
|
separately transforming each of the Java source files into an abstract syntax
|
|
tree and then handing the result over to each of its submodules which in turn
|
|
have a look at certain aspects of the tree.
|
|
</p>
|
|
<p class="body">
|
|
Checkstyle obtains a configuration from an XML document whose elements specify
|
|
the configuration's hierarchy of modules and their properties. You provide
|
|
a file that contains the configuration document when you invoke Checkstyle at
|
|
the <a href="cmdline.html">command line</a>, and when you run a <a href="anttask.html">Checkstyle
|
|
task</a> in ant. The documentation directory of the Checkstyle distribution contains
|
|
a sample configuration file <em>sun_checks.xml</em> which configures Checkstyle
|
|
to check for the Sun coding conventions.
|
|
</p>
|
|
<a name="modules"></a> <h2>Modules</h2>
|
|
<p class="body">
|
|
A <span class="code">module</span> element in the configuration XML document
|
|
specifies a module identified by the element's <span class="code">name</span>
|
|
attribute.
|
|
</p>
|
|
<p class="body">
|
|
Here is a fragment of a typical configuration document:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<module name="PackageHtml"/>
|
|
<module name="TreeWalker">
|
|
<module name="AvoidStarImport"/>
|
|
<module name="ConstantName"/>
|
|
<module name="EmptyBlock"/>
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
In this configuration:
|
|
</p>
|
|
<ul class="body">
|
|
<li>
|
|
Root module <span class="code">Checker</span> has child FileSetChecks <span class="code">
|
|
PackageHtml</span> and <span class="code">TreeWalker</span>. (Module <a href="config_javadoc.html">
|
|
<span class="code">PackageHtml</span></a> checks that all packages have package
|
|
documentation.)
|
|
</li>
|
|
<li>
|
|
Module <span class="code">TreeWalker</span> has submodules
|
|
<span class="code">AvoidStarImport</span>,
|
|
<span class="code">ConstantName</span>, and
|
|
<span class="code">EmptyBlock</span>.
|
|
(Modules
|
|
<a href="config_import.html"><span class="code">AvoidStarImport</span></a>,
|
|
<a href="config_naming.html"><span class="code">ConstantName</span></a>, and
|
|
<a href="config_blocks.html"><span class="code">EmptyBlock</span></a>
|
|
check that a Java source file has no star imports, has
|
|
valid constant names, and has no empty blocks, respectively.)
|
|
</li>
|
|
</ul>
|
|
<p class ="body">
|
|
For each configuration module, Checkstyle loads a class identified by the
|
|
<span class="code">name</span> attribute of the <span class="code">module</span>.
|
|
There are several rules for loading a module's class:
|
|
</p>
|
|
<ol class="body">
|
|
<li>
|
|
Load a class directly according to a package-qualified <span class="code">name</span>,
|
|
such as loading class <span class="code">com.puppycrawl.tools.checkstyle.TreeWalker</span>
|
|
for element
|
|
<pre class="body">
|
|
<module name="com.puppycrawl.tools.checkstyle.TreeWalker">
|
|
</pre>
|
|
This is useful for plugging third-party modules into a configuration.
|
|
</li>
|
|
<li>
|
|
Load a class of a pre-specified package, such as loading class
|
|
<span class="code">com.puppycrawl.tools.checkstyle.checks.AvoidStarImport</span>
|
|
for element
|
|
<pre class="body">
|
|
<module name="AvoidStarImport"/>
|
|
</pre>
|
|
Checkstyle applies packages <span class="code">
|
|
com.puppycrawl.tools.checkstyle</span> and <span class="code">
|
|
com.puppycrawl.tools.checkstyle.checks</span> by default. You can specify other
|
|
packages in a <a href="#packagenames"><em>package names XML document</em></a>
|
|
when you invoke Checkstyle at the <a href="cmdline.html">command line</a>,
|
|
and when you run a <a href="anttask.html">Checkstyle task</a> in ant.
|
|
</li>
|
|
<li>
|
|
Apply the above rules to <span class="code">name</span>
|
|
concatenated with <span class="code">"Check"</span>,
|
|
such as loading class
|
|
<span class="code">com.puppycrawl.tools.checkstyle.checks.ConstantNameCheck</span> for element
|
|
<pre class="body">
|
|
<module name="ConstantName"/>
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
<a name="properties"></a> <h2>Properties</h2>
|
|
<p class="body">
|
|
Properties of a module control how the module performs its checks.
|
|
Each module property has a default value, and you are not required to define a property in the
|
|
configuration document if the default value is satisfactory.
|
|
To assign a non-default value to a module's property,
|
|
define a child <span class="code">property</span> element of the <span class="code">module</span>
|
|
element in the configuration XML document. Also provide appropriate
|
|
<span class="code">name</span> and
|
|
<span class="code">value</span> attributes for the <span class="code">property</span> element.
|
|
For example, property
|
|
<span class="code">max</span> of module <span class="code">MethodLength</span>
|
|
specifies the maximum allowable number of lines in a method or constructor, and has default
|
|
value <span class="code">150</span>.
|
|
Here is a configuration of module <span class="code">MethodLength</span> so that the check reports
|
|
methods and constructors with more than <span class="code">60</span> lines:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength">
|
|
<property name="max" value="60"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
</p>
|
|
<p class="body">
|
|
<a href="cmdline.html">Command line</a> properties
|
|
and ant <a href="anttask.html">Checkstyle task</a> properties apply
|
|
to the root <span class="code">Checker</span>
|
|
module. Also, properties are inherited in the
|
|
module hierarchy. These features make it easy to define one property value that applies to
|
|
many modules. For example, the following configuration fragment specifies that a
|
|
<span class="code">tabWidth</span> of <span class="code">4</span> applies to
|
|
<span class="code">TreeWalker</span> and its submodules:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<module name="PackageHtml"/>
|
|
<module name="TreeWalker">
|
|
<property name="tabWidth" value="4"/>
|
|
<module name="AvoidStarImport"/>
|
|
<module name="ConstantName"/>
|
|
...
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
The value of a module property can be specified through <em>property expansion</em> with the
|
|
<span class="code">${<em>property_name</em>}</span> notation,
|
|
where <span class="code"><em>property_name</em></span> is a <a href="cmdline.html">command line</a>
|
|
property or an ant <a href="anttask.html">Checkstyle task</a> property.
|
|
For example, the following configuration document element gives property
|
|
<span class="code">headerFile</span> the value
|
|
of command line property <span class="code">checkstyle.header.file</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<property name="headerFile" value="${checkstyle.header.file}"/>
|
|
</pre>
|
|
<p class="body">
|
|
You can use property expansion to re-specify a module property value
|
|
without changing the configuration document.
|
|
</p>
|
|
<a name="checker"></a> <h2>Checker</h2>
|
|
<p class="body">
|
|
All configurations have root module <span class="code">Checker</span>.
|
|
<span class="code">Checker</span> contains <em>FileSetCheck</em> children: modules that
|
|
check sets of files.
|
|
<span class="code">Checker</span> also defines properties that are
|
|
inherited by all other modules of a configuration.
|
|
</p>
|
|
<h4 class="body">Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>basedir</td>
|
|
<td>base directory name; stripped off in messages about files</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><span class="default">null</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>localeCountry</td>
|
|
<td>locale country for messages</td>
|
|
<td><a href="property_types.html#string">string</a>: either the empty string or an uppercase ISO 3166 2-letter code</td>
|
|
<td>default locale country for the Java Virtual Machine</td>
|
|
</tr>
|
|
<tr>
|
|
<td>localeLanguage</td>
|
|
<td>locale language for messages</td>
|
|
<td><a href="property_types.html#string">string</a>: either the empty string or a lowercase ISO 639 code</td>
|
|
<td>default locale language for the Java Virtual Machine</td>
|
|
</tr>
|
|
</table>
|
|
<p class="body">
|
|
For example, the following configuration fragment specifies base directory
|
|
<span class="code">src/checkstyle</span> and German locale for all modules:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<property name="basedir" value="src/checkstyle"/>
|
|
<property name="localeCountry" value="DE"/>
|
|
<property name="localeLanguage" value="de"/>
|
|
<module name="PackageHtml"/>
|
|
<module name="TreeWalker">
|
|
...
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
<a name="treewalker"></a> <h2>TreeWalker</h2>
|
|
<p class="body">
|
|
FileSetCheck <span class="code">TreeWalker</span> checks individual Java source files
|
|
and defines properties that are applicable to checking such files.
|
|
</p>
|
|
<h4 class="body">Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>cacheFile</td>
|
|
<td>caches information about files that have checked ok; used to avoid
|
|
repeated checks of the same files</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><span class="default">null</span> (no cache file)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tabWidth</td>
|
|
<td>number of expanded spaces for a tab character (<span class="code">'\t'</span>);
|
|
used in messages and Checks that require a tab width, such as
|
|
<a href="config_sizes.html#LineLength"><span class="code">LineLength</span></a></td>
|
|
<td><a href="property_types.html#integer">integer</a></td>
|
|
<td><span class="default">8</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>fileExtensions</td>
|
|
<td>file type extension to identify java files. Setting this property is
|
|
typically only required if your java source code is preprocessed before
|
|
compilation and the original files do not have the extension
|
|
<span class="code">.java</span></td>
|
|
<td><a href="property_types.html#stringSet">String Set</a></td>
|
|
<td><span class="default">java</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p class="body">
|
|
For example, the following configuration fragment specifies <span class="code">TreeWalker</span>
|
|
cache file <span class="code">target/cachefile</span>, and a <span class="code">tabWidth</span>
|
|
of <span class="code">4</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<module name="TreeWalker">
|
|
<property name="cacheFile" value="target/cachefile"/>
|
|
<property name="tabWidth" value="4"/>
|
|
...
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
<a name="treewalkerchecks"></a> <h2>TreeWalker Checks</h2>
|
|
<p class="body">
|
|
The <span class="code">TreeWalker</span> module creates a syntax tree for a Java source file
|
|
and invokes its submodules, called <em>Checks</em>, during a walk, or traversal, of the nodes
|
|
of the tree.
|
|
Every node of the syntax tree has a token. A visit to a node during the traversal
|
|
triggers all Checks that are configured for its token.
|
|
For example, if Check <span class="code">MethodLength</span> has been configured as
|
|
a submodule of <span class="code">TreeWalker</span>, then a visit to a node
|
|
with a method or a constructor definition
|
|
token triggers <span class="code">MethodLength</span> to check the number of lines
|
|
of the node's code block.
|
|
</p>
|
|
<p class="body">
|
|
Some Checks, such as <span class="code">FileLength</span>
|
|
and <span class="code">LineLength</span>, apply directly to the source file and do not involve tokens
|
|
of the syntax tree.
|
|
Other Checks are associated with configurable sets of tokens that
|
|
trigger the Checks.
|
|
For example, this element configures Check <span class="code">MethodLength</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength"/>
|
|
</pre>
|
|
<p class="body">
|
|
The default token set for <span class="code">MethodLength</span> is
|
|
<span class="code">{METHOD_DEF, CTOR_DEF}</span>, method definition and constructor definition
|
|
tokens, so <span class="code">TreeWalker</span> invokes
|
|
<span class="code">MethodLength</span> whenever it visits a node with a
|
|
<span class="code">METHOD_DEF</span> or a <span class="code">CTOR_DEF</span> token.
|
|
</p>
|
|
<p class="body">
|
|
You specify the trigger tokens for a Check with property <span class="code">tokens</span>.
|
|
The value of <span class="code">tokens</span> is a list that denotes a subset of the Check's
|
|
tokens, as in the following element that configures Check
|
|
<span class="code">MethodLength</span> to check the number of lines of methods only:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength">
|
|
<property name="tokens" value="METHOD_DEF"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To apply particular properties to different subsets of tokens for a Check, repeat the Check.
|
|
For example, to check that the length of each method is at most 150 lines (the default value
|
|
of <span class="code">MethodLength</span> property <span class="code">max</span>) and the
|
|
length of each constructor is at most 60 lines, include the following in the
|
|
<span class="code">TreeWalker</span> configuration:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength">
|
|
<property name="tokens" value="METHOD_DEF"/>
|
|
</module>
|
|
|
|
<module name="MethodLength">
|
|
<property name="tokens" value="CTOR_DEF"/>
|
|
<property name="max" value="60"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
Configurations of the Checks are specified in the following pages:
|
|
</p>
|
|
|
|
<ul class="body">
|
|
<li>
|
|
<a href="config_javadoc.html">Checks For Javadoc Comments</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_naming.html">Checks For Naming Conventions</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_header.html">Checks For Headers</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_import.html">Checks For Imports</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_sizes.html">Checks For Size Violations</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_whitespace.html">Checks For Whitespace</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_modifiers.html">Checks For Modifiers</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_blocks.html">Checks For Blocks</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_coding.html">Checks For Coding Problems</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_design.html">Checks For Design Problems</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_misc.html">Miscellaneous Checks</a>
|
|
</li>
|
|
</ul>
|
|
<a name="packagenames"></a>
|
|
<h2>Packages</h2>
|
|
<p class="body">
|
|
Checkstyle loads a module class according to the <span class="code">name</span>
|
|
of a <span class="code">module</span> element, and automatically appends pre-specified
|
|
package prefixes to that <span class="code">name</span> in its search for a loadable class.
|
|
By default, Checkstyle applies packages <span class="code">
|
|
com.puppycrawl.tools.checkstyle</span> and <span class="code">
|
|
com.puppycrawl.tools.checkstyle.checks</span>. To specify other packages to apply,
|
|
create a <em>package names XML document</em> in a file, and provide that file as a
|
|
<a href="cmdline.html">command line</a> option or as a
|
|
attribute of an <a href="anttask.html">ant Checkstyle task</a>.
|
|
This is useful for integrating other modules in your configuration.
|
|
</p>
|
|
<p class="body">
|
|
A <em>package names XML document</em> specifies a list of package names. Here is the root of the
|
|
default Checkstyle package names XML document for packages <span class="code">
|
|
com.puppycrawl.tools.checkstyle</span> and <span class="code">
|
|
com.puppycrawl.tools.checkstyle.checks</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<checkstyle-packages>
|
|
<package name="com.puppycrawl.tools.checkstyle">
|
|
<package name="checks"/>
|
|
</package>
|
|
</checkstyle-packages>
|
|
</pre>
|
|
<p class="body">
|
|
Notice that the packages are specified recursively - a child
|
|
<span class="code">package</span> element is
|
|
a subpackage of its parent <span class="code">package</span> element.
|
|
</p>
|
|
<p class="body">
|
|
For example, to incorporate modules from package <span class="code">com.mycompany.checks</span>
|
|
with Checkstyle modules, create the XML file below and specify that file as a
|
|
<a href="cmdline.html">command line</a> option or as a
|
|
attribute of an <a href="anttask.html">ant Checkstyle task</a>.:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!DOCTYPE checkstyle-packages PUBLIC
|
|
"-//Puppy Crawl//DTD Package Names 1.0//EN"
|
|
"http://www.puppycrawl.com/dtds/packages_1_0.dtd">
|
|
|
|
<checkstyle-packages>
|
|
<package name="com.mycompany.checks">
|
|
<package name="com.puppycrawl.tools.checkstyle">
|
|
<package name="checks"/>
|
|
</package>
|
|
</checkstyle-packages>
|
|
</pre>
|
|
<p class="body">
|
|
Now you can configure a module of package <span class="code">com.mycompany.checks</span>,
|
|
say <span class="code">com.mycompany.checks.MethodLimitCheck</span>, with a shortened
|
|
<span class="code">module</span> element in the configuration document:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLimit"/>
|
|
</pre>
|
|
<div class="tip">
|
|
<h4 class="tip">Important</h4>
|
|
|
|
If you provide a package names XML document for your own modules and still need to use
|
|
Checkstyle modules, you must include <span class="code">package</span> elements for
|
|
Checkstyle's packages.
|
|
</div>
|
|
<a name="xml"></a>
|
|
<h2>XML Details</h2>
|
|
<h4>Configuration XML Document</h4>
|
|
<p class="body">
|
|
The following DTD for a configuration XML document specifies the hierarchy of modules
|
|
and their properties:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!ELEMENT module (module|property)*>
|
|
<!ATTLIST module name NMTOKEN #REQUIRED>
|
|
|
|
<!ELEMENT property EMPTY>
|
|
<!ATTLIST property
|
|
name NMTOKEN #REQUIRED
|
|
value CDATA #REQUIRED
|
|
>
|
|
</pre>
|
|
<p class="body">
|
|
Checkstyle validates a configuration XML document when it loads the document.
|
|
To validate against the above configuration DTD,
|
|
include the following document type declaration in
|
|
your configuration XML document:
|
|
</p>
|
|
<pre class="body">
|
|
<!DOCTYPE module PUBLIC
|
|
"-//Puppy Crawl//DTD Check Configuration 1.1//EN"
|
|
"http://www.puppycrawl.com/dtds/configuration_1_1.dtd">
|
|
</pre>
|
|
<p class="body">
|
|
Checkstyle also strictly enforces the encoding attribute of an XML declaration.
|
|
If Checkstyle rejects your configuration document's encoding,
|
|
correct the value of the encoding attribute, or remove the encoding attribute entirely.
|
|
</p>
|
|
<p class="body">
|
|
For a complete example of a configuration XML document, examine file <span class="code">docs/checkstyle_checks.xml</span>
|
|
that the Checkstyle team uses to validate the Checkstyle source code.
|
|
</p>
|
|
<h4>Package Names XML Document</h4>
|
|
<p class="body">
|
|
This is a DTD for a package names XML document:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!ELEMENT checkstyle-packages (package)*>
|
|
|
|
<!ELEMENT package (package)*>
|
|
<!ATTLIST package name NMTOKEN #REQUIRED>
|
|
</pre>
|
|
<p class="body">
|
|
Checkstyle also validates a package names XML document when it loads the document.
|
|
To validate against the above package names DTD,
|
|
include the following document type declaration in
|
|
your package names XML document:
|
|
</p>
|
|
<pre class="body">
|
|
<!DOCTYPE checkstyle-packages PUBLIC
|
|
"-//Puppy Crawl//DTD Package Names 1.0//EN"
|
|
"http://www.puppycrawl.com/dtds/packages_1_0.dtd">
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr />
|
|
<div><a href="index.html">Back to the Checkstyle Home Page</a></div>
|
|
<p class="copyright">
|
|
Copyright © 2002-2003 Oliver Burn. All rights Reserved.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|