Checkstyle Command Line - Version 2.3

Description

This document describes how to run checkstyle using the command line tool. The latest version of checkstyle can be found at http://checkstyle.sourceforge.net. This command line tool is included in the checkstyle distribution.

Installation

The easiest way is to include checkstyle-all-2.3.jar in the classpath. This contains all the classes required to run checkstyle. Alternatively, you must include the following in the classpath:

  1. checkstyle-2.3.jar
  2. ANTLR 2.7.1 classes. antlr.jar is included in the distribution.
  3. Jakarta Regexp 1.2 classes. jakarta-regexp-1.2.jar is included in the distribution.

Usage

The command line usage is:

  java -D<property>=<value>  \
       com.puppycrawl.tools.checkstyle.Main \
       [-f <format>] [-p <propertiesFile>] [-o <file>] [-r <dir>] file...

Checkstyle will process the specified files and by default report errors to standard out in plain format. The options are:

The default behaviour of checkstyle can be changed either by setting system properties using the -D<property>=<value> arguments to java or by specifying a property file using the -p option. If a property file is specified the system properties are ignored. The following table describes what properties can be set:

Property Description
checkstyle.lcurly.type Specifies the policy of where to put the left brace '{' for type declarations. The legal values are defined here. Defaults to "eol".
checkstyle.lcurly.method Specifies the policy of where to put the left brace '{' for method declarations. The legal values are defined here. Defaults to "eol".
checkstyle.lcurly.other Specifies the policy of where to put the left brace '{' for other declarations. The keywords covered is defined here. The legal values are defined here. Defaults to "eol".
checkstyle.rcurly Specifies the policy of where to put the right brace '}'. The keywords covered is defined here. The legal values are defined here. Defaults to "same".
checkstyle.paren.pad Specifies the policy of how to pad parenthesises. The legal values are defined here. Defaults to "nospace".
checkstyle.block.try Specifies the policy of how check try blocks. The legal values are defined here. Defaults to "stmt".
checkstyle.block.catch Specifies the policy of how check catch blocks. The legal values are defined here. Defaults to "text".
checkstyle.block.finally Specifies the policy of how check finally blocks. The legal values are defined here. Defaults to "text".
checkstyle.wrap.operator Specifies the policy of how to wrap on operators. The legal values are defined here. Defaults to "nl".
checkstyle.allow.protected Indicates whether to allow protected data. Defaults to "no".
checkstyle.allow.tabs Indicates whether to allow tabs. Defaults to "no".
checkstyle.allow.package Indicates whether to allow package visible data. Defaults to "no".
checkstyle.allow.noauthor Indicates whether to allow no @author tag to be defined for class and interface Javadoc comments. Defaults to "no".
checkstyle.maxlinelen Specifies the maximum line length. Default value is defined here.
checkstyle.tab.width The distance between tab stops, used in line number and column calculations. Default value is "8".
checkstyle.ignore.maxlinelen Specifies a regular expression for lines to ignore in maximum line length checks. Defaults to "^$".
checkstyle.ignore.importlength Specifies whether to ignore the maximum line length for import statements. Defaults to "no".
checkstyle.maxmethodlen Specifies the maximum method length. Default value is defined here.
checkstyle.maxconstructorlen Specifies the maximum constructor length. Default value is defined here.
checkstyle.maxfilelen Specifies the maximum file length. Default value is defined here.
checkstyle.pattern.todo Specifies the regular expression to match for to-do comments. Default value is defined here.
checkstyle.pattern.member Specifies the regular expression to match against member variables. Default value is defined here.
checkstyle.pattern.publicmember Specifies the regular expression to match against public member variables. Default value is defined here.
checkstyle.pattern.parameter Specifies the regular expression to match against parameters. Default value is defined here.
checkstyle.pattern.const Specifies the regular expression to match against static/final variables. Default value is defined here.
checkstyle.pattern.static Specifies the regular expression to match against static variables. Default value is defined here.
checkstyle.pattern.type Specifies the regular expression to match against type names. Default value is defined here.
checkstyle.pattern.method Specifies the regular expression to match against method names. Default value is defined here.
checkstyle.pattern.localvar Specifies the regular expression to match against local variable names. Default value is defined here.
checkstyle.header.file Specifies the file containing the header lines. Default is to not check.
checkstyle.header.regexp Specifies whether to interpret each line in the checkstyle.header.file as a regular expression. Default is "no".
checkstyle.header.ignoreline Specifies a comma separated list of the lines in the header to ignore when comparing. Default is to not ignore any line.
checkstyle.javadoc.scope Specifies the visibility scope where javadoc comments are checked. Valid values are "nothing", "public", "protected", "package", "private" and "anoninner". Defaults to "private".
checkstyle.require.packagehtml Specifies whether to require that package documentation is available. Defaults to "no".
checkstyle.ignore.imports Specifies whether to ignore checking import statements. Defaults to "no".
checkstyle.illegal.imports Comma separated list of package prefixes that are not allowed in import statements. Defaults to "sun".
checkstyle.illegal.instantiations Comma separated list of fully qualified class names that are not allowed to be instantiated. Defaults to "".
checkstyle.ignore.whitespace Specifies whether to ignore checking whitespace. Defaults to "no".
checkstyle.ignore.whitespace.cast Specifies whether to ignore checking for whitespace after a cast. Defaults to "no".
checkstyle.ignore.braces Specifies whether to ignore checking braces. Defaults to "no".
checkstyle.ignore.longell Specifies whether to ignore checking the L in long integer literals. Defaults to "false".
checkstyle.ignore.public.in.interface Specifies whether to ignore the public keyword in interface definitions. Defaults to "no".
checkstyle.cache.file Specifies the name of a file that can be used to cache details of files that pass checkstyle. This can signicantly increase the speed of checkstyle on successive runs.
checkstyle.javadoc.checkUnusedThrows Specifies whether to check if unused @throws tags are subclasses of java.lang.RuntimeException. Defaults to "false".
checkstyle.basedir Specifies a base directory for reporting file names relative to. Defaults to "".

Older versions of the checkstyle task supported the boolean parameters checkstyle.javadoc.relax and checkstyle.javadoc.ignore. These parameters have been removed because they were conflicting with each other and the semantics of relaxJavadoc was not specified. The two parameters have been replaced by the checkstyle.javadoc.scope parameter. Instead of checkstyle.javadoc.ignore=true you can now use checkstyle.javadoc.scope=nothing. The behaviour of checkstyle.javadoc.relax=true is roughly the same as checkstyle.javadoc.scope=protected.

Examples

Run checkstyle on a file

  java  com.puppycrawl.tools.checkstyle.Main  Check.java

Run checkstyle on all java files in a directory

  java  com.puppycrawl.tools.checkstyle.Main -r src/

Run checkstyle on a file and allow tabs

  java  -Dcheckstyle.allow.tabs=yes \
        com.puppycrawl.tools.checkstyle.Main Check.java

Run checkstyle on a file and output to a file in XML format

  java  -Dcheckstyle.allow.tabs=yes  \
        com.puppycrawl.tools.checkstyle.Main \
        -f xml -o build/checkstyle_errors.xml Check.java

Run checkstyle on a file and disable pattern matching

  java  -Dcheckstyle.pattern.parameter=. \
        -Dcheckstyle.pattern.static=. \
        -Dcheckstyle.pattern.const=. \
        -Dcheckstyle.pattern.member=. \
        com.puppycrawl.tools.checkstyle.Main Check.java

Tip

It is possible to run Checkstyle directly from the JAR file using the -jar option. Example would be:

  java  -jar checkstyle-all-2.3.jar  Check.java

Copyright © 2001 Oliver Burn. All rights Reserved.