345 lines
15 KiB
HTML
345 lines
15 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="#treewalker">TreeWalker Checks</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.
|
|
</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 also specify
|
|
packages 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 all
|
|
FileSetCheck<em></em>s and their submodules:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<property name="tabWidth" value="4"/>
|
|
<module name="PackageHtml"/>
|
|
<module name="TreeWalker">
|
|
<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="treewalker"></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_misc.html">Miscellaneous Checks</a>
|
|
</li>
|
|
</ul>
|
|
<a name="xml"></a>
|
|
<h2>XML Details</h2>
|
|
<p class="body">
|
|
The following is a 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.0//EN"
|
|
"http://www.puppycrawl.com/dtds/configuration_1_0.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 echoing 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>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr />
|
|
<p>
|
|
Copyright © 2002 Oliver Burn. All rights Reserved.
|
|
</p>
|
|
|
|
</body>
|
|
</html> |