<?xml version="1.0" encoding="ISO-8859-1"?>

<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">

  <properties>
    <title>Command Line</title>
    <author>Oliver Burn</author>
  </properties>

  <body>

    <section name="Description">
      <p>
        This document describes how to run Checkstyle using the command line
        tool. The latest version of Checkstyle can be found at <a
        href="http://checkstyle.sourceforge.net">http://checkstyle.sourceforge.net</a>.
        This command line tool is included in the Checkstyle distribution.
      </p>
    </section>

    <section name="Installation">
      <p>
        The easiest way is to include
        <code>checkstyle-${projectVersion}-all.jar</code> in the
        classpath. Alternatively, you must include the
        <code>compile</code> third party dependencies listed in

        <a href="dependencies.html">Project Dependencies</a> in the
        classpath.
      </p>
    </section>

    <section name="Usage">
      <p>
        The command line usage is:
      </p>

      <source>
java -D&lt;property&gt;=&lt;value&gt;  \
     com.puppycrawl.tools.checkstyle.Main \
     -c &lt;configurationFile&gt; \
     [-f &lt;format&gt;] [-p &lt;propertiesFile&gt;] [-o &lt;file&gt;] \
     [-r &lt;dir&gt;] file...
      </source>

      <p>
        Checkstyle will process the specified files and by default report
        errors to standard out in plain format. Checkstyle requires a <a
        href="config.html">configuration XML file</a> that configures the
        checks to apply. Command line options are:
      </p>

      <ul>
        <li>
          <code>-c configurationFile</code> - specifies the location of the
          file that defines the configuration modules. The location can either
          be a filesystem location, or a name passed to the
          ClassLoader.getResource() method.
        </li>
        <li>
          <code>-f format</code> - specify the output
          format. Options are <code> "plain"</code> for the <a
          href="apidocs/com/puppycrawl/tools/checkstyle/DefaultLogger.html">DefaultLogger</a>
          and <code>"xml"</code> for the <a
          href="apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a>.
          Defaults to <code>"plain"</code>.
        </li>
        <li>
          <code>-p propertiesFile</code> - specify a
          properties file to use.
        </li>
        <li>
          <code>-o file</code> - specify the file to output
          to.
        </li>
        <li>
          <code>-r dir</code> - specify the directory to
          traverse for Java source files.
        </li>
      </ul>

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

      <p>
        Set the properties for <a href="config.html#Properties">expanded
        property values</a> by either by assigning system properties using the
        <code>-D&lt;property&gt;=&lt;value&gt;</code> arguments to java or
        specifying a property file using the <code>-p</code> option.  If a
        property file is specified, the system properties are ignored.
      </p>
    </section>

    <section name="Examples">
      <p>
        <b>
          Run checkstyle with configuration file
          <code>docs/sun_checks.xml</code> on a file
        </b>
      </p>
      <source>
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \
     Check.java
      </source>

      <p>
        <b>
          Run checkstyle with configuration file
          <code>docs/sun_checks.xml</code> on all java files in a directory
        </b>
      </p>
      <source>
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \
     -r src/
      </source>

      <p>
        <b>
          Run checkstyle with configuration file
          <code>docs/sun_checks.xml</code> on a file and provide a system
          property
        </b>
      </p>
      <source>
java -Dcheckstyle.cache.file=target/cachefile \
     com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \
     Check.java
      </source>

      <p>
        <b>
          Run checkstyle with configuration file
          <code>docs/sun_checks.xml</code> on a file and use properties in a
          file
        </b>
      </p>
      <source>
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \
     -p myCheckstyle.properties Check.java
      </source>

      <p>
        <b>
          Run checkstyle with configuration file
          <code>docs/sun_checks.xml</code> on a file and output to a file in
          XML format
        </b>
      </p>
      <source>
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \
     -f xml -o build/checkstyle_errors.xml Check.java
      </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>
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \
     -n myPackageNames.xml Check.java
      </source>

      <div class="tip">
        <h4 class="tip">Tip</h4>
        <p>
          It is possible to run Checkstyle directly from the JAR file using
          the <code>-jar</code> option. An example would be:
        </p>

        <source>
java -jar checkstyle-${projectVersion}-all.jar \
     -c docs/sun_checks.xml Check.java
        </source>
      </div>
    </section>
  </body>
</document>

