| <?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>Command Line</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> |
| <section name="Content"> |
| <macro name="toc"> |
| <param name="fromDepth" value="1"/> |
| <param name="toDepth" value="1"/> |
| </macro> |
| </section> |
| |
| <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="Command line usage"> |
| <p> |
| |
| <source> |
| java -D<property>=<value> \ |
| com.puppycrawl.tools.checkstyle.Main \ |
| -c <configurationFile> \ |
| [-f <format>] [-p <propertiesFile>] [-o <file>] \ |
| [-t | --tree] [-T | --treeWithComments] [-J | treeWithJavadoc] [-j | --javadocTree] [-v] \ |
| file... |
| </source> |
| </p> |
| |
| <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 <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html#res_names">name</a> 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>-t, --tree</code> - print Abstract Syntax Tree(AST) of the checked file. The option |
| cannot be used other options and requires exactly one file to run on to be specified. |
| </li> |
| <li> |
| <code>-T, --treeWithComments</code> - print Abstract Syntax Tree(AST) with comment nodes of the checked file. The option |
| cannot be used other options and requires exactly one file to run on to be specified. |
| </li> |
| <li> |
| <code>-J, --treeWithJavadoc</code> - print Abstract Syntax Tree(AST) with Javadoc nodes and comment nodes |
| of the checked file. Attention that line number and columns will not be the same as it is a file due to the fact |
| that each javadoc comment is parsed separately from java file. The option cannot be used other options and requires |
| exactly one file to run on to be specified. |
| </li> |
| <li> |
| <code>-j, --javadocTree</code> - print Parse Tree of the Javadoc comment. |
| The file have to contain <b>only Javadoc comment content</b> without including '/**' and '*/' at the beginning and at the end respectively. |
| For example: |
| MyTestFile.javadoc |
| <source> |
| |
| * Test method. |
| * @return true |
| |
| </source> |
| The option |
| cannot be used other options and requires exactly one file to run on to be specified. |
| </li> |
| <li> |
| <code>-d, --debug</code> - Print all debug logging of CheckStyle utility. |
| </li> |
| <li> |
| <code>-e, --exclude excludedDirectory</code> - Directory to exclude from |
| CheckStyle. The directory can be the full, absolute path, or relative to the current path. |
| Multiple excludes are allowed. |
| </li> |
| <li> |
| <code>-x, --exclude-regexp excludedDirectoryPattern</code> - Directory pattern to exclude from |
| CheckStyle. Multiple excludes are allowed. |
| </li> |
| <li> |
| <code>-v</code> - print product version and exit. Any other option is ignored. |
| </li> |
| <li> |
| <code>-executeIgnoredModules</code> - Allows ignored modules to be run. |
| </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<property>=<value></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="Download and Run"> |
| <p> |
| It is possible to run Checkstyle directly from the JAR file using |
| the <code>-jar</code> option. Download latest <a href="http://downloads.sourceforge.net/project/checkstyle/checkstyle/${projectVersion}/checkstyle-${projectVersion}-all.jar"> |
| checkstyle-${projectVersion}-all.jar</a>. |
| An example of run would be: |
| <source class="wrap-content"> |
| java -jar checkstyle-${projectVersion}-all.jar -c /sun_checks.xml MyClass.java |
| java -jar checkstyle-${projectVersion}-all.jar -c /google_checks.xml MyClass.java |
| </source> |
| It is recommended to use configuration files that are embedded in jar files, but latest configuration files are there: |
| <a href="https://raw.githubusercontent.com/checkstyle/checkstyle/master/src/main/resources/sun_checks.xml">sun_checks.xml</a> |
| <a href="https://raw.githubusercontent.com/checkstyle/checkstyle/master/src/main/resources/google_checks.xml">google_checks.xml</a> |
| </p> |
| <p> |
| To run <a href="writingchecks.html#The_Checkstyle_SDK_Gui">Checkstyle UI viewer</a> for AST tree directly from the JAR file using |
| the <code>-jar</code> option. Download latest <a href="http://downloads.sourceforge.net/project/checkstyle/checkstyle/${projectVersion}/checkstyle-${projectVersion}-all.jar"> |
| checkstyle-${projectVersion}-all.jar</a>. |
| An example of run would be (path to java file is optional): |
| <source class="wrap-content"> |
| java -cp checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.gui.Main MyClass.java |
| </source> |
| </p> |
| </section> |
| |
| <section name="Run after compilation"> |
| <p> |
| Download and compile: |
| <source class="wrap-content"> |
| git clone https://github.com/checkstyle/checkstyle.git |
| cd checkstyle |
| mvn clean compile |
| </source> |
| |
| Run validation with arguments: |
| <source class="wrap-content"> |
| mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.Main" -Dexec.args="-c /sun_checks.xml src/main/java " |
| </source> |
| Run UI application for file : |
| <source class="wrap-content"> |
| mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.gui.Main" -Dexec.args="src/main/java/com/puppycrawl/tools/checkstyle/Checker.java" |
| </source> |
| Build all jars, and launch CLI from new build: |
| <source class="wrap-content"> |
| mvn clean package -Passembly |
| java -jar target/checkstyle-X.X-SNAPSHOT-all.jar -c /sun_checks.xml MyClass.java |
| </source> |
| </p> |
| </section> |
| |
| <section name="Usage by Classpath update"> |
| <p> |
| The easiest way is to include |
| <a href="http://downloads.sourceforge.net/project/checkstyle/checkstyle/${projectVersion}/checkstyle-${projectVersion}-all.jar">checkstyle-${projectVersion}-all.jar</a> in the |
| <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html#sthref10">classpath</a>. Alternatively, you must include the |
| <code>compile</code> third party dependencies listed in |
| |
| <a href="dependencies.html">Project Dependencies</a> in the |
| classpath. |
| |
| <br/> |
| <br/> |
| <b> |
| Run checkstyle with configuration file at |
| <code>docs/sun_checks.xml</code> on a filesystem |
| </b> |
| </p> |
| <source class="wrap-content"> |
| 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 class="wrap-content"> |
| java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml 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 class="wrap-content"> |
| 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 class="wrap-content"> |
| 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 class="wrap-content"> |
| 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 <a href="extending.html">custom module(s) |
| (Root module, Checks, etc)</a> in configuration file: |
| </b> |
| </p> |
| <source class="wrap-content"> |
| java -classpath MyCustom.jar;checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.Main -c config.xml Check.java |
| </source> |
| <p> |
| <b>Note</b>: Custom modules should be specified with the class' |
| <a href="writingchecks.html#Integrate_your_Check">full classpath</a> |
| in the configuration file and the compiled class be located in the custom |
| JAR for Checkstyle to find. |
| </p> |
| </section> |
| </body> |
| </document> |
| |
