866 lines
31 KiB
XML
866 lines
31 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>Configuration</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>
|
|
<!-- till https://issues.apache.org/jira/browse/MSITE-748
|
|
<section name="Content">
|
|
<macro name="toc">
|
|
<param name="fromDepth" value="1"/>
|
|
<param name="toDepth" value="1"/>
|
|
</macro>
|
|
</section> -->
|
|
|
|
<section name="Overview">
|
|
<p>
|
|
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:
|
|
</p>
|
|
|
|
<ul>
|
|
|
|
<li><em>FileSetChecks</em> - modules that take a set of input
|
|
files and fire error messages.</li>
|
|
|
|
<li><em>Filters</em>
|
|
|
|
- modules that filter audit events,
|
|
including error messages, for acceptance.</li>
|
|
|
|
<li><em>AuditListeners</em> - modules that report accepted events.</li>
|
|
|
|
</ul>
|
|
|
|
<p>
|
|
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>
|
|
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>
|
|
</section>
|
|
|
|
<section name="Modules">
|
|
<p>
|
|
A <code>module</code> element in the configuration
|
|
XML document specifies a module identified by the element's
|
|
<code>name</code> attribute.
|
|
</p>
|
|
|
|
<p>
|
|
Here is a fragment of a typical configuration document:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<module name="JavadocPackage"/>
|
|
<module name="TreeWalker">
|
|
<module name="AvoidStarImport"/>
|
|
<module name="ConstantName"/>
|
|
<module name="EmptyBlock"/>
|
|
</module>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
In this configuration:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
Root module <code>Checker</code> has child
|
|
FileSetChecks <code>JavadocPackage</code> and <code>TreeWalker</code>. (Module <a
|
|
href="config_javadoc.html"> <code>JavadocPackage</code></a> checks that all packages
|
|
have package documentation.)
|
|
</li>
|
|
<li>
|
|
Module <code>TreeWalker</code> has submodules
|
|
<code>AvoidStarImport</code>, <code>ConstantName</code>, and <code>EmptyBlock</code>. (Modules <a
|
|
href="config_imports.html"><code>AvoidStarImport</code></a>, <a
|
|
href="config_naming.html"><code>ConstantName</code></a>, and <a
|
|
href="config_blocks.html"><code>EmptyBlock</code></a> check that a Java source
|
|
file has no star imports, has valid constant names, and has no
|
|
empty blocks, respectively.)
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
For each configuration module, Checkstyle loads a class
|
|
identified by the <code>name</code> attribute of
|
|
the <code>module</code>. There are several rules
|
|
for loading a module's class:
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
Load a class directly according to a package-qualified <code>name</code>, such as loading class <code>com.puppycrawl.tools.checkstyle.TreeWalker</code>
|
|
for element:
|
|
|
|
<source>
|
|
<module name="com.puppycrawl.tools.checkstyle.TreeWalker"/>
|
|
</source>
|
|
|
|
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
|
|
<code>com.puppycrawl.tools.checkstyle.checks.AvoidStarImport</code>
|
|
for element
|
|
<source>
|
|
<module name="AvoidStarImport"/>
|
|
</source>
|
|
|
|
Checkstyle applies packages <code>
|
|
com.puppycrawl.tools.checkstyle</code>, <code>
|
|
com.puppycrawl.tools.checkstyle.filters</code>, and <code> com.puppycrawl.tools.checkstyle.checks</code>
|
|
and its sub-packages (only those included in the Checkstyle
|
|
distribution). You can specify other packages in a <a
|
|
href="#Packages"><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 <code>name</code>
|
|
concatenated with <code>"Check"</code>,
|
|
such as loading class <code>com.puppycrawl.tools.checkstyle.checks.ConstantNameCheck</code>
|
|
for element
|
|
<source>
|
|
<module name="ConstantName"/>
|
|
</source>
|
|
</li>
|
|
</ol>
|
|
</section>
|
|
|
|
<section name="Properties">
|
|
<p>
|
|
Properties of a module control how the module performs its task.
|
|
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 <code>property</code> element of the <code>module</code> element in the configuration XML
|
|
document. Also provide appropriate <code>name</code> and <code>value</code>
|
|
attributes for the <code>property</code> element.
|
|
For example, property <code>max</code> of module
|
|
<code>MethodLength</code> specifies the maximum
|
|
allowable number of lines in a method or constructor, and has
|
|
default value <code>150</code>. Here is a
|
|
configuration of module <code>MethodLength</code>
|
|
so that the check reports methods and constructors with more
|
|
than <code>60</code> lines:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="MethodLength">
|
|
<property name="max" value="60"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
<a href="cmdline.html">Command line</a> properties and ant <a
|
|
href="anttask.html">Checkstyle task</a> properties apply to the
|
|
root <code>Checker</code> 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 <code>tabWidth</code> of <code>4</code> applies to <code>TreeWalker</code> and its submodules:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<module name="JavadocPackage"/>
|
|
<module name="TreeWalker">
|
|
<property name="tabWidth" value="4"/>
|
|
<module name="AvoidStarImport"/>
|
|
<module name="ConstantName"/>
|
|
...
|
|
</module>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
The value of a module property can be specified through
|
|
<em>property expansion</em> with the <code>${<em>property_name</em>}</code> notation, where
|
|
<code><em>property_name</em></code> 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
|
|
<code>headerFile</code> the value of command line
|
|
property <code>checkstyle.header.file</code>:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Header">
|
|
<property name="headerFile" value="${checkstyle.header.file}"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
You can use property expansion to re-specify a module property
|
|
value without changing the configuration document.
|
|
</p>
|
|
|
|
<p>
|
|
The property element provides an optional <code>default</code> attribute which is used when a
|
|
property in the value cannot be resolved. For example this
|
|
configuration snippet from a central configuration file checks
|
|
that methods have javadoc, but allows individual projects to
|
|
override the severity by specifying their desired value in the
|
|
command line property <code>checkstyle.javadoc.severity</code>:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="JavadocMethod">
|
|
<property name="severity"
|
|
value="${checkstyle.javadoc.severity}"
|
|
default="error"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
This feature is a great help when setting up a centralized
|
|
configuration file (e.g. one file for the whole company) to
|
|
lower configuration maintenance costs. Projects that are happy
|
|
with the default can simply use that configuration file as is,
|
|
but individual projects with special needs have the flexibility
|
|
to adjust a few settings to fit their needs without having to
|
|
copy and maintain the whole configuration.
|
|
</p>
|
|
|
|
<p>
|
|
You can find information about property types on
|
|
<a href="property_types.html">Property Types</a> page.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section name="Checker">
|
|
|
|
<p>
|
|
All configurations have root module <code>Checker</code>. <code>Checker</code>
|
|
contains:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><em>FileSetCheck</em> children: modules that check sets of
|
|
files.</li>
|
|
<li><em>Filter</em> children: modules that filter audit
|
|
events.</li>
|
|
<li><em>AuditListener</em> children: modules that report
|
|
filtered events.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<code>Checker</code> also defines properties that are
|
|
inherited by all other modules of a configuration.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
<table>
|
|
<tr>
|
|
<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><code>null</code></td>
|
|
</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><code>null</code> (no cache file)</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>
|
|
<tr>
|
|
<td>charset</td>
|
|
<td>name of the file charset</td>
|
|
<td><a href="property_types.html#string">String</a></td>
|
|
<td>System property "file.encoding"</td>
|
|
</tr>
|
|
<tr>
|
|
<td>fileExtensions</td>
|
|
<td>file extensions that are accepted</td>
|
|
<td><a href="property_types.html#string">String</a> array</td>
|
|
<td><code>null</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
For example, the following configuration fragment specifies base
|
|
directory <code>src/checkstyle</code>, cache file <code>target/cachefile</code> and German
|
|
locale for all modules:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<property name="basedir" value="src/checkstyle"/>
|
|
<property name="cacheFile" value="target/cachefile"/>
|
|
<property name="localeCountry" value="DE"/>
|
|
<property name="localeLanguage" value="de"/>
|
|
<module name="JavadocPackage"/>
|
|
<module name="TreeWalker">
|
|
...
|
|
</module>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
To configure a <code>Checker</code> so that it
|
|
handles files with the <code>UTF-8</code> charset:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<property name="charset" value="UTF-8"/>
|
|
...
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
To configure a <code>Checker</code> so that it
|
|
handles files with the <code>java, xml, properties</code> extensions:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<property name="fileExtensions" value="java, xml, properties"/>
|
|
...
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
To configure a <code>Checker</code> so that it
|
|
handles files with any extension:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<property name="fileExtensions" value="null"/>
|
|
...
|
|
</module>
|
|
</source>
|
|
<p>OR</p>
|
|
<source>
|
|
<module name="Checker">
|
|
<property name="fileExtensions" value=""/>
|
|
...
|
|
</module>
|
|
</source>
|
|
|
|
</section>
|
|
|
|
<section name="TreeWalker">
|
|
<p>
|
|
FileSetCheck <code>TreeWalker</code> checks
|
|
individual Java source files and defines properties that are
|
|
applicable to checking such files.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>tabWidth</td>
|
|
<td>number of expanded spaces for a tab character (<code>'\t'</code>); used in messages and Checks that
|
|
require a tab width, such as <a
|
|
href="config_sizes.html#LineLength"><code>LineLength</code></a></td>
|
|
<td><a href="property_types.html#integer">integer</a></td>
|
|
<td><code>8</code></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 <code>.java</code></td>
|
|
<td><a href="property_types.html#stringSet">String Set</a></td>
|
|
<td><code>java</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
For example, the following configuration fragment specifies
|
|
<code>TreeWalker</code> a <code>tabWidth</code> of <code>4</code>:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<module name="TreeWalker">
|
|
<property name="tabWidth" value="4"/>
|
|
...
|
|
</module>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
<!--
|
|
thanks to Paul King for this example, see
|
|
https://sourceforge.net/tracker/?func=detail&aid=865610&group_id=29721&atid=397078
|
|
-->
|
|
To integrate Checkstyle with BEA Weblogic Workshop 8.1:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Checker">
|
|
<module name="TreeWalker">
|
|
<property name="fileExtensions" value="java,ejb,jpf"/>
|
|
...
|
|
</module>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
To configure <code>TreeWalker</code> so that it
|
|
handles files with the <code>java</code> extension:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="TreeWalker">
|
|
<property name="fileExtensions" value="java"/>
|
|
...
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
To configure <code>TreeWalker</code> so that it
|
|
handles files with any extension:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="TreeWalker">
|
|
<property name="fileExtensions" value="null"/>
|
|
...
|
|
</module>
|
|
</source>
|
|
<p>OR</p>
|
|
<source>
|
|
<module name="TreeWalker">
|
|
<property name="fileExtensions" value=""/>
|
|
...
|
|
</module>
|
|
</source>
|
|
|
|
</section>
|
|
|
|
<section name="TreeWalker Checks">
|
|
|
|
<p>
|
|
The <code>TreeWalker</code> 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 <code>MethodLength</code> has been configured as a
|
|
submodule of <code>TreeWalker</code>, then a visit
|
|
to a node with a method or a constructor definition token
|
|
triggers <code>MethodLength</code> to check the
|
|
number of lines of the node's code block.
|
|
</p>
|
|
|
|
<p>
|
|
Some Checks, such as <code>FileLength</code> and
|
|
<code>LineLength</code>, 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
|
|
<code>MethodLength</code>:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="MethodLength"/>
|
|
</source>
|
|
|
|
<p>
|
|
The default token set for <code>MethodLength</code>
|
|
is <code>{METHOD_DEF, CTOR_DEF}</code>, method
|
|
definition and constructor definition tokens, so <code>TreeWalker</code> invokes <code>MethodLength</code> whenever it visits a node with
|
|
a <code>METHOD_DEF</code> or a <code>CTOR_DEF</code> token.
|
|
</p>
|
|
|
|
<p>
|
|
You specify the trigger tokens for a Check with property <code>tokens</code>. The value of <code>tokens</code> is a list that denotes a subset of
|
|
the Check's tokens, as in the following element that configures
|
|
Check <code>MethodLength</code> to check the number
|
|
of lines of methods only:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="MethodLength">
|
|
<property name="tokens" value="METHOD_DEF"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
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
|
|
<code>MethodLength</code> property <code>max</code>) and the length of each constructor is
|
|
at most 60 lines, include the following in the <code>TreeWalker</code> configuration:
|
|
</p>
|
|
|
|
<source>
|
|
<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>
|
|
</source>
|
|
|
|
<p>
|
|
Configurations of the Checks are specified in the pages under <a
|
|
href="checks.html">here</a>.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section name="Severity">
|
|
<p>
|
|
Each check has a <a
|
|
href="property_types.html#severity">severity</a> property that a
|
|
Checkstyle audit assigns to all violations of the check. The
|
|
default severity level of a check is <code>error</code>.
|
|
</p>
|
|
|
|
<p>
|
|
You can use the severity property to control the output of the
|
|
plain formatter for the <a href="cmdline.html">command line
|
|
tool</a> and the <a href="anttask.html">ANT task</a>. The plain
|
|
formatter does not report violations with severity level <code>ignore</code>, and notes violations with
|
|
severity level <code>warning</code>. For
|
|
example, according to the following configuration fragment, the
|
|
plain formatter outputs warnings for translation violations:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Translation">
|
|
<property name="severity" value="warning"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
The XML formatter reports the severity level of every violation
|
|
as an attribute of the violation's <code>error</code> element.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Custom messages">
|
|
<p>
|
|
As of Checkstyle 5 all checks can be configured to report
|
|
custom, configuration specific messages instead of the
|
|
Checkstyle default messages. This can be useful in cases where
|
|
the check message should reference corresponding sections in a
|
|
coding style document or the default is too generic for
|
|
developers to understand.
|
|
</p>
|
|
|
|
<p>An example usage is:</p>
|
|
|
|
<source>
|
|
<module name="MemberName">
|
|
<property name="format" value="^m[a-zA-Z0-9]*$"/>
|
|
<message key="name.invalidPattern"
|
|
value="Member ''{0}'' must start with a lowercase ''m'' (checked pattern ''{1}'')."
|
|
/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
Each check configuration element can have zero or more <code>message</code> elements. Every check uses one or
|
|
more distinct message keys to log violations. If you want to
|
|
customize a certain message you need to specify the message key
|
|
in the <code>key</code> attribute of the <code>message</code> element.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>value</code> attribute specifies the
|
|
custom message pattern, as shown in the example above.
|
|
Placeholders used in the default message can also be used in the
|
|
custom message. Note that the message pattern must be a valid
|
|
<code>java.text.MessageFormat</code> style pattern,
|
|
so be careful about curly braces outside a placeholder
|
|
definition.
|
|
</p>
|
|
|
|
<p>
|
|
The obvious question is how do you know which message keys a
|
|
Check uses, so that you can override them? You can examine all
|
|
keys in the check's specific <a href="checks.html">configuration
|
|
documentation</a>. Each check has a section called 'Error Messages'.
|
|
This section lists every key the check uses and links to the default
|
|
message used by checkstyle.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Filters">
|
|
|
|
<p>
|
|
A Checker module has a set of Filter submodules to filter audit
|
|
events, including the error messages fired by Checks. A Filter
|
|
can accept or reject an audit event. If all Filters accept an
|
|
audit event, then the Checker reports the event. If any Filter
|
|
rejects an event, then the Checker does not report the
|
|
event. For more information please visit
|
|
<a href="config_filters.html">filters page</a>.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section name="AuditListeners">
|
|
|
|
<p>
|
|
In addition to an audit reporter for text or XML output, a
|
|
Checker can have <a href="writinglisteners.html">custom
|
|
AuditListeners</a> that handle audit events. In order to use a
|
|
custom listener, add a <code>Checker</code> submodule for the
|
|
listener and its properties. For example, to configure a <code>Checker</code> so that it uses custom listener <a
|
|
href="writinglisteners.html#Writing_Listeners">VerboseListener</a> to
|
|
print audit messages to a file named "audit.txt",
|
|
include the following module in the configuration file:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="com.mycompany.listeners.VerboseListener">
|
|
<property name="file" value="audit.txt"/>
|
|
</module>
|
|
</source>
|
|
|
|
</section>
|
|
|
|
<section name="Packages">
|
|
<p>
|
|
Checkstyle loads a module class according to the <code>name</code> of a <code>module</code>
|
|
element, and automatically appends pre-specified package
|
|
prefixes to that <code>name</code> in its search
|
|
for a loadable class. By default, Checkstyle applies packages
|
|
<code> com.puppycrawl.tools.checkstyle</code>,
|
|
<code>
|
|
com.puppycrawl.tools.checkstyle.filters</code>, and <code> com.puppycrawl.tools.checkstyle.checks</code> as
|
|
well as any sub-packages of <code>com.puppycrawl.tools.checkstyle.checks</code> that
|
|
are distributed with Checkstyle.
|
|
</p>
|
|
<p>
|
|
To specify other packages to apply,
|
|
create a <em>package names XML document</em> in a file
|
|
named <code>checkstyle_packages.xml</code>,
|
|
and provide that file in the root of the .jar containing your
|
|
custom checks.
|
|
</p>
|
|
<p>
|
|
Note that the support for providing a <em>package names XML document</em>
|
|
via <a href="cmdline.html">command line</a> option or as a attribute
|
|
of an <a href="anttask.html">ant Checkstyle task</a> has been dropped
|
|
with Checkstyle 5.0.
|
|
</p>
|
|
|
|
<p>
|
|
A <em>package names XML document</em> specifies a list of
|
|
package names. Here is a sample package names XML document for
|
|
packages <code>
|
|
com.puppycrawl.tools.checkstyle</code> and <code>
|
|
com.puppycrawl.tools.checkstyle.checks</code>:
|
|
</p>
|
|
|
|
<source>
|
|
<checkstyle-packages>
|
|
<package name="com.puppycrawl.tools.checkstyle">
|
|
<package name="checks"/>
|
|
</package>
|
|
</checkstyle-packages>
|
|
</source>
|
|
|
|
<p>
|
|
Notice that the packages are specified recursively - a child
|
|
<code>package</code> element is a subpackage of its
|
|
parent <code>package</code> element.
|
|
</p>
|
|
|
|
<p>
|
|
For example, to incorporate modules from package <code>com.mycompany.checks</code> with Checkstyle
|
|
modules, create the XML file below and put this file into the
|
|
<b>root of the jar</b> file which contains your custom check modules.
|
|
The XML file must be named exactly <code>checkstyle_packages.xml</code>:
|
|
</p>
|
|
|
|
<source>
|
|
<?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"/>
|
|
</checkstyle-packages>
|
|
</source>
|
|
|
|
<p>
|
|
Now you can configure a module of package <code>com.mycompany.checks</code>, say <code>com.mycompany.checks.MethodLimitCheck</code>, with
|
|
a shortened <code>module</code> element in the
|
|
configuration document:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="MethodLimit"/>
|
|
</source>
|
|
|
|
<div class="tip">
|
|
<h4>Note</h4>
|
|
<p>
|
|
As of Checkstyle 5.0 it is unnecessary to repeat the
|
|
<code>package</code> elements for Checkstyle's packages in
|
|
your custom <code>checkstyle_packages.xml</code> file.
|
|
</p>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section name="XML Structure">
|
|
|
|
<h4>Configuration XML Document</h4>
|
|
<p>
|
|
The following DTD for a configuration XML document specifies the
|
|
hierarchy of modules and their properties:
|
|
</p>
|
|
|
|
<source>
|
|
<?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
|
|
>
|
|
</source>
|
|
|
|
<p>
|
|
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>
|
|
|
|
<source>
|
|
<!DOCTYPE module PUBLIC
|
|
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
|
|
"http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
|
|
</source>
|
|
|
|
<p>
|
|
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>
|
|
For a complete example of a configuration XML document, examine
|
|
file <code>docs/sun_checks.xml</code> that checks the Sun coding
|
|
conventions.
|
|
</p>
|
|
|
|
<h4>Package Names XML Document</h4>
|
|
<p>
|
|
This is a DTD for a package names XML document:
|
|
</p>
|
|
|
|
<source>
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!ELEMENT checkstyle-packages (package)*>
|
|
|
|
<!ELEMENT package (package)*>
|
|
<!ATTLIST package name NMTOKEN #REQUIRED>
|
|
</source>
|
|
|
|
<p>
|
|
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>
|
|
|
|
<source>
|
|
<!DOCTYPE checkstyle-packages PUBLIC
|
|
"-//Puppy Crawl//DTD Package Names 1.1//EN"
|
|
"http://www.puppycrawl.com/dtds/packages_1_1.dtd">
|
|
</source>
|
|
|
|
<h4>Suppressions XML Document</h4>
|
|
<p>
|
|
This is a DTD for a suppressions XML document:
|
|
</p>
|
|
|
|
<source>
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!ELEMENT suppressions (suppress*)>
|
|
|
|
<!ELEMENT suppress EMPTY>
|
|
<!ATTLIST suppress files CDATA #REQUIRED
|
|
checks CDATA #IMPLIED
|
|
id CDATA #IMPLIED
|
|
lines CDATA #IMPLIED
|
|
columns CDATA #IMPLIED>
|
|
</source>
|
|
|
|
</section>
|
|
</body>
|
|
</document>
|