anttask.html

<!DOCTYPE html>


<!--
 | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/anttask.xml.vm at 2025-03-04
 | Rendered using Apache Maven Fluido Skin 2.0.1
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
    <title>Ant Task – checkstyle</title>
    <link rel="stylesheet" href="./css/apache-maven-fluido-2.0.1.min.css" />
    <link rel="stylesheet" href="./css/site.css" />
    <link rel="stylesheet" href="./css/print.css" media="print" />
    <script src="./js/apache-maven-fluido-2.0.1.min.js"></script>
<script type="text/javascript" src="./js/checkstyle.js"></script>
        <script type="text/javascript"
              src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
        <script type="text/javascript" src="./js/anchors.js"></script>
        <script type="text/javascript" src="./js/google-analytics.js"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/prettify/r298/prettify.min.js"></script>
        <script type="text/javascript"
              src="https://cdn.jsdelivr.net/gh/google/code-prettify@master/loader/run_prettify.js"></script>
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prettify/r298/prettify.min.css">
        <link rel="icon" href="./images/favicon.png" type="image/x-icon" />
        <link rel="shortcut icon" href="./images/favicon.ico" type="image/ico" />
  </head>
  <body>
    <div class="container-fluid container-fluid-top">
      <header>
        <div id="banner">
          <div class="pull-left"><div id="bannerLeft"><h1><a href="./"><img class="class java.lang.Object" src="images/header-checkstyle-logo.png" alt="Checkstyle" /></a></h1></div></div>
          <div class="pull-right"><div id="bannerRight"><h1><img class="class java.lang.Object" src="images/header-right-ruller.png" alt="Checkstyle" /></h1></div></div>
          <div class="clear"><hr/></div>
        </div>

        <div id="breadcrumbs">
          <ul class="breadcrumb">
        <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2025-03-04</li>
          <li id="projectVersion" class="pull-right"><span class="divider">|</span>Version: 10.21.4</li>
        <li class="pull-right"><a>toTop</a></li>
          </ul>
        </div>
      </header>
      <div class="row-fluid">
        <header id="leftColumn" class="span2">
          <nav class="well sidebar-nav">
  <ul class="nav nav-list">
   <li class="nav-header">About</li>
    <li><a href="index.html">Checkstyle</a></li>
    <li><a href="releasenotes.html">Release Notes</a></li>
    <li><a href="consulting.html">Consulting</a></li>
    <li><a href="sponsoring.html">Sponsoring</a></li>
   <li class="nav-header">Documentation</li>
    <li><a href="config.html"><span class="icon-chevron-down"></span>Configuration</a>
     <ul class="nav nav-list">
      <li><a href="property_types.html">Property Types</a></li>
      <li><a href="config_system_properties.html">System Properties</a></li>
     </ul></li>
    <li><a href="running.html"><span class="icon-chevron-down"></span>Running</a>
     <ul class="nav nav-list">
      <li class="active"><a>Ant Task</a></li>
      <li><a href="cmdline.html">Command Line</a></li>
     </ul></li>
    <li><a href="checks.html"><span class="icon-chevron-down"></span>Checks</a>
     <ul class="nav nav-list">
      <li><a href="checks/annotation/index.html"><span class="icon-chevron-right"></span>Annotations</a></li>
      <li><a href="checks/blocks/index.html"><span class="icon-chevron-right"></span>Block Checks</a></li>
      <li><a href="checks/design/index.html"><span class="icon-chevron-right"></span>Class Design</a></li>
      <li><a href="checks/coding/index.html"><span class="icon-chevron-right"></span>Coding</a></li>
      <li><a href="checks/header/index.html"><span class="icon-chevron-right"></span>Headers</a></li>
      <li><a href="checks/imports/index.html"><span class="icon-chevron-right"></span>Imports</a></li>
      <li><a href="checks/javadoc/index.html"><span class="icon-chevron-right"></span>Javadoc Comments</a></li>
      <li><a href="checks/metrics/index.html"><span class="icon-chevron-right"></span>Metrics</a></li>
      <li><a href="checks/misc/index.html"><span class="icon-chevron-right"></span>Miscellaneous</a></li>
      <li><a href="checks/modifier/index.html"><span class="icon-chevron-right"></span>Modifiers</a></li>
      <li><a href="checks/naming/index.html"><span class="icon-chevron-right"></span>Naming Conventions</a></li>
      <li><a href="checks/regexp/index.html"><span class="icon-chevron-right"></span>Regexp</a></li>
      <li><a href="checks/sizes/index.html"><span class="icon-chevron-right"></span>Size Violations</a></li>
      <li><a href="checks/whitespace/index.html"><span class="icon-chevron-right"></span>Whitespace</a></li>
     </ul></li>
    <li><a href="filters/index.html"><span class="icon-chevron-right"></span>Filters</a></li>
    <li><a href="filefilters/index.html"><span class="icon-chevron-right"></span>File Filters</a></li>
    <li><a href="style_configs.html"><span class="icon-chevron-down"></span>Style Configurations</a>
     <ul class="nav nav-list">
      <li><a href="google_style.html">Google&apos;s Style</a></li>
      <li><a href="sun_style.html">Sun&apos;s Style</a></li>
     </ul></li>
   <li class="nav-header">Developers</li>
    <li><a href="extending.html"><span class="icon-chevron-down"></span>Extending Checkstyle</a>
     <ul class="nav nav-list">
      <li><a href="writingchecks.html">Writing Checks</a></li>
      <li><a href="writingjavadocchecks.html">Writing Javadoc Checks</a></li>
      <li><a href="writingfilters.html">Writing Filters</a></li>
      <li><a href="writingfilefilters.html">Writing File Filters</a></li>
      <li><a href="writinglisteners.html">Writing Listeners</a></li>
     </ul></li>
    <li><a href="contributing.html">Contributing</a></li>
    <li><a href="beginning_development.html"><span class="icon-chevron-down"></span>Beginning Development</a>
     <ul class="nav nav-list">
      <li><a href="eclipse.html">Eclipse IDE</a></li>
      <li><a href="netbeans.html">NetBeans IDE</a></li>
      <li><a href="idea.html">IntelliJ IDE</a></li>
     </ul></li>
    <li><a href="apidocs/index.html">Javadoc</a></li>
   <li class="nav-header">Project Documentation</li>
    <li><a href="project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
    <li><a href="project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
  </ul>
          </nav>
          <div class="well sidebar-nav">
            <div id="poweredBy">
              <div class="clear"></div>
              <div class="clear"></div>
<a href="https://github.com/checkstyle/checkstyle" class="builtBy"><img class="builtBy" src="images/github_logo_social_coding_outlined.png" alt="GitHub" /></a>
<a href="https://twitter.com/checkstyle_java/" class="builtBy"><img class="builtBy" src="images/twitter_button.png" alt="Twitter" /></a>
<a href="https://stackoverflow.com/questions/tagged/checkstyle" class="builtBy"><img class="builtBy" src="images/stackoverflow.jpeg" alt="Stackoverflow" /></a>
<a href="https://groups.google.com/forum/#!forum/checkstyle" class="builtBy"><img class="builtBy" src="images/groups.png" alt="GoogleGroups" /></a>
<a href="https://www.ej-technologies.com/products/jprofiler/overview.html" class="builtBy"><img class="builtBy" src="https://www.ej-technologies.com/images/product_banners/jprofiler_medium.png" alt="JProfiler" /></a>
            </div>
          </div>
        </header>
        <main id="bodyColumn" class="span10">


    <section><a id="Content"></a>
<h1>Content</h1>
      
        
<ul>
<li><a href="#Content">Content</a></li>
<li><a href="#Description">Description</a></li>
<li><a href="#Installation">Installation</a></li>
<li><a href="#Parameters">Parameters</a></li>
<li><a href="#Nested_Elements">Nested Elements</a></li>
<li><a href="#Examples">Examples</a></li></ul>
    </section>

    <section><a id="Description"></a>
<h1>Description</h1>

      
<p>
        This task runs Checkstyle over specified Java files.
        The latest version of checkstyle can be found at
        <a href="./index.html">https://checkstyle.org/</a>.

        This task is included in the checkstyle distribution.
      </p>

    </section>

    <section><a id="Installation"></a>
<h1>Installation</h1>

      
<p>
        The easiest way is to include
        <code>checkstyle-10.21.4-all.jar</code> in the
        classpath. This contains all the classes required to run
        Checkstyle. Alternatively, you must include the
        <code>compile</code> third party dependencies listed in <a href="dependencies.html">Project Dependencies</a> in the
        classpath.
      </p>

      
<p>
        To use the task in a build file, you will need the following
        <code>taskdef</code> declaration:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;taskdef resource=&quot;com/puppycrawl/tools/checkstyle/ant/checkstyle-ant-task.properties&quot;
         classpath=&quot;/path/to/checkstyle-10.21.4-all.jar&quot;/&gt;
      </code></pre></div>

      
<p>
        Or, assuming that Checkstyle is in the global classpath (not
        recommended), then you will need the following <code>taskdef</code>
        declaration:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;taskdef
  resource=&quot;com/puppycrawl/tools/checkstyle/ant/checkstyle-ant-task.properties&quot;/&gt;
      </code></pre></div>

      
<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="https://ant.apache.org/manual/Types/antlib.html" class="externalLink">https://ant.apache.org/manual/Types/antlib.html</a>
        for more details).  For example:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;project name=&quot;foo&quot; ...
         xmlns:cs=&quot;antlib:com.puppycrawl.tools.checkstyle.ant&quot;&gt;
...
  &lt;cs:checkstyle&gt;
  ...
  &lt;/cs:checkstyle&gt;
...
&lt;/project&gt;
      </code></pre></div>

    </section>

    <section><a id="Parameters"></a>
<h1>Parameters</h1>

      
<div class="wrapper">
        
<table class="table table-striped">

          
<tr class="a">
            
<td><b>Attribute</b></td>
            
<td><b>Description</b></td>
            
<td><b>Required</b></td>
          </tr>

          
<tr class="b">
            
<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> or <i>path</i>
              element
            </td>
          </tr>

          
<tr class="a">
            
<td>fileset</td>
            
<td>
              A set of files to run checkstyle on. Nested attribute.
              See <a href="https://ant.apache.org/manual/Types/fileset.html" class="externalLink">fileset</a>
              ant documentation for details
            </td>
            
<td>
              One of either <i>file</i> or at least one nested <i>fileset</i> or <i>path</i>
              element
            </td>
          </tr>

          
<tr class="b">
            
<td>path</td>
            
<td>
              A set of path to run checkstyle on. Nested attribute.
              See <a href="https://ant.apache.org/manual/using.html#path" class="externalLink">path</a>
              ant documentation for details
            </td>
            
<td>
              One of either <i>file</i> or at least one nested <i>fileset</i> or <i>path</i>
              element
            </td>
          </tr>

          
<tr class="a">
            
<td>config</td>
            
<td>
              Specifies the location of the file, URL, or Java resource that defines the
              configuration modules.
              <br />
              <a href="config.html">See here</a> for a description of how to
              define a configuration.
            </td>
            
<td>Exactly one config location</td>
          </tr>

          
<tr class="b">
            
<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 class="a">
            
<td>failOnViolation</td>
            
<td>
              Specifies whether the build will continue even if there are
              violations. Defaults to <code>&quot;true&quot;</code>.
            </td>
            
<td>No</td>
          </tr>

          
<tr class="b">
            
<td>failureProperty</td>
            
<td>The name of a property to set in the event of a violation.</td>
            
<td>No</td>
          </tr>

          
<tr class="a">
            
<td>maxErrors</td>
            
<td>
              The maximum number of errors that are tolerated before
              breaking the build or setting the failure property. Defaults
              to <code>&quot;0&quot;</code>.
            </td>
            
<td>No</td>
          </tr>

          
<tr class="b">
            
<td>maxWarnings</td>
            
<td>
              The maximum number of warnings that are tolerated before
              breaking the build or setting the failure property. Defaults
              to <code>&quot;2147483647&quot;</code>, i.e.

              <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html#MAX_VALUE" class="externalLink">
                  Integer.MAX_VALUE</a>.
            </td>
            
<td>No</td>
          </tr>

          
<tr class="a">
            
<td>executeIgnoredModules</td>
            
<td>
              For efficiency, Checkstyle does not invoke modules with a configured severity of
              &quot;ignore&quot; (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. These settings specify that behaviour.
              Defaults to <code>&quot;false&quot;</code>.
            </td>
            
<td>No</td>
          </tr>
        </table>
      </div>

      
<p>
        Note that the <code>packageNamesFile</code>
        parameter has been dropped for Checkstyle 5.0, because of
        significant changes regarding package name file handling. See <a href="config.html#Packages"></a> for details.
      </p>

      
<p>
        Also note, that checkstyle ignores all duplicate files,
        specified in the <i>file</i>, <i>fileset</i> or <i>path</i> parameters
      </p>
    </section>

    <section><a id="Nested_Elements"></a>
<h1>Nested Elements</h1>

      
<p>
        This task supports the nested elements <a href="https://ant.apache.org/manual/Types/fileset.html" class="externalLink">&lt;fileset&gt;</a>,
        <a href="https://ant.apache.org/manual/using.html#path" class="externalLink">&lt;classpath&gt;</a>,
        <a href="https://ant.apache.org/manual/using.html#path" class="externalLink">&lt;path&gt;</a>,
        <code>&lt;formatter&gt;</code>, and <code>&lt;property&gt;</code>.
      </p>

      
<p>
        The parameters for the <code>&lt;formatter&gt;</code>
        element are:
      </p>

      
<div class="wrapper">
        
<table class="table table-striped">
          
<tr class="a">
            
<td><b>Attribute</b></td>
            
<td><b>Description</b></td>
            
<td><b>Required</b></td>
          </tr>

          
<tr class="b">
            
<td>type</td>
            
<td>
              
<p>The type of output to generate. The valid values are:</p>
              
<ul>
                
<li>
                  <code>plain</code> - specifies the <a href="apidocs/com/puppycrawl/tools/checkstyle/DefaultLogger.html">
                    DefaultLogger</a>
                </li>
                
<li>
                  <code>xml</code> - specifies the <a href="apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a>
                </li>
                
<li>
                  <code>sarif</code> - specifies the <a href="apidocs/com/puppycrawl/tools/checkstyle/SarifLogger.html">SarifLogger</a>
                </li>
              </ul>
              
<p>Defaults to <code>&quot;plain&quot;</code>.</p>
            </td>
            
<td>No</td>
          </tr>

          
<tr class="a">
            
<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 class="b">
            
<td>useFile</td>
            
<td>Boolean that determines whether output should be sent to
            a file.  Default is <code>true</code>.</td>
            
<td>No</td>
          </tr>
        </table>
      </div>

      
<p>
        A <code>&lt;property&gt;</code> element provides a property for
        <a href="config.html#Properties">expanded property values</a> of
        the configuration.  The parameters for the
        <code>&lt;property&gt;</code> element are:
      </p>

      
<div class="wrapper">
        
<table class="table table-striped">
          
<tr class="a">
            
<td><b>Attribute</b></td>
            
<td><b>Description</b></td>
            
<td><b>Required</b></td>
          </tr>
          
<tr class="b">
            
<td>key</td>
            
<td>
<p>The key for the property.</p></td>
            
<td>Yes</td>
          </tr>

          
<tr class="a">
            
<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 class="b">
            
<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>
      </div>

    </section>

    <section><a id="Examples"></a>
<h1>Examples</h1>

      
<p>
        An example project can be found
        <a href="https://github.com/sevntu-checkstyle/checkstyle-samples/tree/master/ant-project" class="externalLink">
            here</a>.
      </p>

      
<p>
        <b>
          Checkstyle use ant configuration to validate its own code. See example is our git
          repository -
          <a href="https://github.com/checkstyle/checkstyle/blob/master/config/ant-phase-verify.xml#L25" class="externalLink">
            config/ant-phase-verify.xml</a>.
        </b>
      </p>

      
<p>
        <b>
          Run checkstyle with configuration file
          <code>docs/sun_checks.xml</code> on a single file
        </b>
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;checkstyle config=&quot;docs/sun_checks.xml&quot; file=&quot;Check.java&quot;/&gt;
      </code></pre></div>

      
<p>
        <b>
          Run checkstyle on a set of Java files using site-wide configuration
          and an expanded property value
        </b>
      </p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&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;
      </code></pre></div>

      
<p>
        <b>
          Run checkstyle on a previously defined source path.
        </b>
      </p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;!-- Somewhere in your config --&gt;
&lt;path id=&quot;project.sourcepath&quot;&gt;
  &lt;fileset dir=&quot;src&quot;
          includes=&quot;**/*&quot;
          excludes=&quot;it/resources/**/*,test/resources/**/*,test/resources-noncompilable/**/*&quot;/&gt;
&lt;/path&gt;

&lt;!-- Actual checkstyle config --&gt;
&lt;checkstyle config=&quot;/path/to/site/sun_checks.xml&quot;&gt;
  &lt;!-- Refer to a previously defined source path --&gt;
  &lt;path refid=&quot;project.sourcepath&quot; /&gt;
&lt;/checkstyle&gt;
      </code></pre></div>

      
<p>
        <b>
          Run checkstyle on a set of files and output messages to standard
          output in plain format, and files in XML &amp; SARIF format
        </b>
      </p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&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;formatter type=&quot;sarif&quot; toFile=&quot;build/checkstyle_errors.sarif&quot;/&gt;
&lt;/checkstyle&gt;
      </code></pre></div>

      
<p>
        <b>
          Run checkstyle with configuration file
          <code>docs/sun_checks.xml</code> on a file and provide a package
          names file
        </b>
      </p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;checkstyle config=&quot;docs/sun_checks.xml&quot;
            packageNamesFile=&quot;myPackageNames.xml&quot;
            file=&quot;Check.java&quot;/&gt;
      </code></pre></div>

      
<p>
        <b>
          Run checkstyle in an automated build and send an email report if
          style violations are detected
        </b>
      </p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;target name=&quot;checkstyle&quot;
        description=&quot;Generates a report of code convention violations.&quot;&gt;

  &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;
      </code></pre></div>

      
<p>
        <b>
          To run checkstyle with a custom JAR with implementation of custom Checks
          be sure the custom JAR is found on the classpath. An example can be found at
          <a href="https://github.com/sevntu-checkstyle/checkstyle-samples/tree/master/ant-project" class="externalLink">
          checkstyle-samples</a>.
        </b>
      </p>

    </section>
  
        </main>
      </div>
    </div>
    <hr/>
    <footer>
      <div class="container-fluid">
        <div class="row-fluid">
            <p>©      2001–2025
</p>
        </div>
      </div>
    </footer>
  </body>
</html>