TouchInstinct
/
checkstyle
308
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
checkstyle/src/xdocs/anttask.xml

423 lines
13 KiB
XML
Executable File
Raw Blame History

<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Ant Task</title>
<author>Oliver Burn</author>
</properties>
<body>
<section name="Description">
<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>
</section>
<section name="Installation">
<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 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>
<source>
&lt;taskdef resource=&quot;checkstyletask.properties&quot;
classpath=&quot;/path/to/checkstyle-all-@CHECKSTYLE_VERSION@.jar&quot;/&gt;
</source>
<p>
Or, assuming that Checkstyle is in the global classpath (not
recommended), then you will need the following <code>taskdef</code>
declaration:
</p>
<source>
&lt;taskdef resource=&quot;checkstyletask.properties&quot;/&gt;
</source>
<p>
Or if you use Ant 1.6 and later and assuming that Checkstyle
is in the library search path, then you may use antlib feature
of Ant (see <a
href="http://ant.apache.org/manual/CoreTypes/antlib.html"
>http://ant.apache.org/manual/CoreTypes/antlib.html</a>
for more details). For example:
</p>
<source>
&lt;project name="foo" ...
xmlns:cs="antlib:com.puppycrawl.tools.checkstyle"&gt;
...
&lt;cs:checkstyle&gt;
...
&lt;/cs:checkstyle&gt;
...
&lt;/project&gt;
</source>
</section>
<section name="Parameters">
<table summary="parameters">
<tr>
<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>
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>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>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>No</td>
</tr>
<tr>
<td>packageNamesFile</td>
<td>
Specifies a file that contains <a href="config.html#Packages">
package names</a> for the configuration.
</td>
<td>No</td>
</tr>
<tr>
<td>failOnViolation</td>
<td>
Specifies whether the build will continue even if there are
violations. Defaults to <span
class="default">&quot;true&quot;</span>.
</td>
<td>No</td>
</tr>
<tr>
<td>failureProperty</td>
<td>The name of a property to set in the event of a violation.</td>
<td>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">&quot;0&quot;</span>.
</td>
<td>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">&quot;2147483647&quot;</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>No</td>
</tr>
<tr>
<td>classpath</td>
<td>
The classpath to use when looking up classes. Defaults to the
current classpath.
</td>
<td>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>No</td>
</tr>
<tr>
<td>omitIgnoredModules</td>
<td>
For efficiency, Checkstyle does not invoke modules with a configured severity of "ignore"
(since their output would be ignored anyway). A small number of modules may choose to log above their
configured severity level and so always need to be invoked. This settings specifies that behaviour.
Defaults to <span class="default">&quot;true&quot;</span>.
</td>
<td>No</td>
</tr>
</table>
</section>
<section name="Nested Elements">
<p>
This task supports the nested elements <a
href="http://ant.apache.org/manual/CoreTypes/fileset.html">&lt;fileset&gt;</a>,
<a
href="http://ant.apache.org/manual/using.html#path">&lt;classpath&gt;</a>,
<span class="default">&lt;formatter&gt;</span>, and <span
class="default">&lt;property&gt;</span>.
</p>
<p>
The parameters for the <span class="default">&lt;formatter&gt;</span>
element are:
</p>
<table summary="nested elements">
<tr>
<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>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>No</td>
</tr>
<tr>
<td>useFile</td>
<td>Boolean that determines whether output should be sent to
a file. Default is <span class="default">true</span>.</td>
<td>No</td>
</tr>
</table>
<p>
A <span class="default">&lt;property&gt;</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">&lt;property&gt;</span> element are:
</p>
<table summary="nested elements">
<tr>
<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>Yes</td>
</tr>
<tr>
<td>value</td>
<td>The value of the property specified as a string.</td>
<td>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>Either <i>value</i> or <i>file</i></td>
</tr>
</table>
</section>
<section name="Examples">
<p>
<b>
Run checkstyle with configuration file
<code>docs/sun_checks.xml</code> on a single file
</b>
</p>
<source>
&lt;checkstyle config=&quot;docs/sun_checks.xml&quot; file=&quot;Check.java&quot;/&gt;
</source>
<p>
<b>
Run checkstyle on a set of Java files using site-wide configuration
and an expanded property value
</b>
</p>
<source>
&lt;checkstyle config=&quot;/path/to/site/sun_checks.xml&quot;&gt;
&lt;fileset dir=&quot;src/checkstyle&quot; includes=&quot;**/*.java&quot;/&gt;
&lt;!-- Location of cache-file. Something that is project specific --&gt;
&lt;property key=&quot;checkstyle.cache.file&quot; file=&quot;target/cachefile&quot;/&gt;
&lt;/checkstyle&gt;
</source>
<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>
<source>
&lt;checkstyle config=&quot;docs/sun_checks.xml&quot;&gt;
&lt;fileset dir=&quot;src/checkstyle&quot; includes=&quot;**/*.java&quot;/&gt;
&lt;formatter type=&quot;plain&quot;/&gt;
&lt;formatter type=&quot;xml&quot; toFile=&quot;build/checkstyle_errors.xml&quot;/&gt;
&lt;/checkstyle&gt;
</source>
<p>
<b>
Run checkstyle with configuration file
<code>docs/sun_checks.xml</code> on a file and provide a package
names file
</b>
</p>
<source>
&lt;checkstyle config=&quot;docs/sun_checks.xml&quot;
packageNamesFile=&quot;myPackageNames.xml&quot;
file=&quot;Check.java&quot;/&gt;
</source>
<p>
<b>
Run checkstyle in an automated build and send an email report if
style violations are detected
</b>
</p>
<source>
&lt;target name=&quot;checkstyle&quot;
description=&quot;Generates a report of code convention violations.&quot;>
&lt;checkstyle config=&quot;docs/sun_checks.xml&quot;
failureProperty=&quot;checkstyle.failure&quot;
failOnViolation=&quot;false&quot;&gt;
&lt;formatter type=&quot;xml&quot; tofile=&quot;checkstyle_report.xml&quot;/&gt;
&lt;fileset dir=&quot;src&quot; includes=&quot;**/*.java&quot;/&gt;
&lt;/checkstyle&gt;
&lt;style in=&quot;checkstyle_report.xml&quot; out=&quot;checkstyle_report.html&quot; style=&quot;checkstyle.xsl&quot;/&gt;
&lt;/target&gt;
&lt;!-- run this target as part of automated build --&gt;
&lt;target name=&quot;checkstyle-nightly&quot;
depends=&quot;checkstyle&quot;
if=&quot;checkstyle.failure&quot;
description=&quot;Sends email if checkstyle detected code conventions violations.&quot;&gt;
&lt;!-- use your own server and email addresses below. See Ant documentation for details --&gt;
&lt;mail from=&quot;qa@some.domain&quot;
tolist=&quot;someone@some.domain,someoneelse@some.domain&quot;
mailhost=&quot;mailbox.some.domain&quot;
subject=&quot;Checkstyle violation(s) in project ${ant.project.name}&quot;
files=&quot;checkstyle_report.html&quot;/&gt;
&lt;/target&gt;
</source>
</section>
</body>
</document>
Reference in New Issue View Git Blame Copy Permalink