checkstyle:check

Full name:

org.apache.maven.plugins:maven-checkstyle-plugin:2.15:check

Description:

Performs Checkstyle analysis and outputs violations or a count of violations to the console, potentially failing the build. It can also be configured to re-use an earlier analysis.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: verify.

Required Parameters

Name Type Since Description
includeResources boolean 2.11 Whether to apply Checkstyle to resource directories.
Default value is: true.
User property is: checkstyle.includeResources.
includeTestResources boolean 2.11 Whether to apply Checkstyle to test resource directories.
Default value is: true.
User property is: checkstyle.includeTestResources.
includes String - Specifies the names filter of the source files to be used for Checkstyle.
Default value is: **\/*.java.
User property is: checkstyle.includes.
resourceIncludes String 2.11 Specifies the names filter of the files to be used for Checkstyle when checking resources.
Default value is: **/*.properties.
User property is: checkstyle.resourceIncludes.

Optional Parameters

Name Type Since Description
cacheFile String - Specifies the cache file used to speed up Checkstyle on successive runs.
Default value is: ${project.build.directory}/checkstyle-cachefile.
checkstyleRules PlexusConfiguration 2.12 By using this property, you can specify the whole Checkstyle rules inline directly inside this pom. 
<plugin>
  ...
  <configuration>
    <checkstyleRules>
      <module name="Checker">
        <module name="FileTabCharacter">
          <property name="eachLine" value="true" />
        </module>
        <module name="TreeWalker">
          <module name="EmptyBlock"/>
        </module>
      </module>
    </checkstyleRules>
  </configuration>
  ...

configLocation String 2.5

Specifies the location of the XML configuration to use.

Potential values are a filesystem path, a URL, or a classpath resource. This parameter expects that the contents of the location conform to the xml format (Checkstyle Checker module) configuration of rulesets.

This parameter is resolved as resource, URL, then file. If successfully resolved, the contents of the configuration is copied into the ${project.build.directory}/checkstyle-configuration.xml file before being passed to Checkstyle as a configuration.

There are 2 predefined rulesets.

  • config/sun_checks.xml: Sun Checks.
  • config/maven_checks.xml: Maven Source Checks.

Default value is: config/sun_checks.xml.
User property is: checkstyle.config.location.
consoleOutput boolean - Output errors to console.
Default value is: false.
User property is: checkstyle.consoleOutput.
encoding String 2.2 The file encoding to use when reading the source files. If the property project.build.sourceEncoding is not set, the platform default encoding is used. Note: This parameter always overrides the property charset from Checkstyle's TreeWalker module.
Default value is: ${project.build.sourceEncoding}.
User property is: encoding.
excludes String - Specifies the names filter of the source files to be excluded for Checkstyle.
User property is: checkstyle.excludes.
failOnViolation boolean - Fail the build on a violation. The goal checks for the violations after logging them (if logViolationsToConsole is 'true'). Compare this to failsOnError which fails the build immediately before examining the output log.
Default value is: true.
User property is: checkstyle.failOnViolation.
failsOnError boolean - If this is true, and Checkstyle reported any violations or errors, the build fails immediately after running Checkstyle, before checking the log for logViolationsToConsole. If you want to use logViolationsToConsole, use failOnViolation instead of this.
Default value is: false.
headerLocation String 2.0-beta-2

Specifies the location of the License file (a.k.a. the header file) that can be used by Checkstyle to verify that source code has the correct license header.

You need to use ${checkstyle.header.file} in your Checkstyle xml configuration to reference the name of this header file.

For instance:

<module name="RegexpHeader"> <property name="headerFile" value="${checkstyle.header.file}"/> </module>


Default value is: LICENSE.txt.
User property is: checkstyle.header.file.
includeTestSourceDirectory boolean 2.2 Include or not the test source directory to be used for Checkstyle.
Default value is: false.
logViolationsToConsole boolean 2.3 Output the detected violations to the console.
Default value is: true.
User property is: checkstyle.console.
maxAllowedViolations int 2.3 The maximum number of allowed violations. The execution fails only if the number of violations is above this limit.
Default value is: 0.
User property is: checkstyle.maxAllowedViolations.
outputFile File - Specifies the path and filename to save the Checkstyle output. The format of the output file is determined by the outputFileFormat parameter.
Default value is: ${project.build.directory}/checkstyle-result.xml.
User property is: checkstyle.output.file.
outputFileFormat String - Specifies the format of the output to be used when writing to the output file. Valid values are "plain" and "xml".
Default value is: xml.
User property is: checkstyle.output.format.
propertiesLocation String 2.5

Specifies the location of the properties file.

This parameter is resolved as URL, File then resource. If successfully resolved, the contents of the properties location is copied into the ${project.build.directory}/checkstyle-checker.properties file before being passed to Checkstyle for loading.

The contents of the propertiesLocation will be made available to Checkstyle for specifying values for parameters within the xml configuration (specified in the configLocation parameter).


User property is: checkstyle.properties.location.
propertyExpansion String - Allows for specifying raw property expansion information.
resourceExcludes String 2.11 Specifies the names filter of the files to be excluded for Checkstyle when checking resources.
User property is: checkstyle.resourceExcludes.
rulesFiles File - dump file for inlined Checkstyle rules
Default value is: ${project.build.directory}/checkstyle-rules.xml.
User property is: checkstyle.output.rules.file.
skip boolean 2.2 Skip entire check.
Default value is: false.
User property is: checkstyle.skip.
skipExec boolean 2.5 Skip Checkstyle execution will only scan the outputFile.
Default value is: false.
User property is: checkstyle.skipExec.
sourceDirectories List 2.13 Specifies the location of the source directories to be used for Checkstyle.
Default value is: ${project.compileSourceRoots}.
sourceDirectory File - Deprecated. instead use sourceDirectories
suppressionsFileExpression String 2.1 The key to be used in the properties for the suppressions file.
Default value is: checkstyle.suppressions.file.
User property is: checkstyle.suppression.expression.
suppressionsLocation String 2.0-beta-2

Specifies the location of the suppressions XML file to use.

This parameter is resolved as resource, URL, then file. If successfully resolved, the contents of the suppressions XML is copied into the ${project.build.directory}/checkstyle-suppressions.xml file before being passed to Checkstyle for loading.

See suppressionsFileExpression for the property that will be made available to your Checkstyle configuration.


User property is: checkstyle.suppressions.location.
testSourceDirectories List 2.13 Specifies the location of the test source directories to be used for Checkstyle.
Default value is: ${project.testCompileSourceRoots}.
testSourceDirectory File 2.2 Deprecated. instead use testSourceDirectories
useFile File - If null, the Checkstyle plugin will display violations on stdout. Otherwise, a text file will be created with the violations.
violationIgnore String 2.13 Violations to ignore. This is a comma-separated list, each value being either a rule name, a rule category or a java package name of rule class.
User property is: checkstyle.violation.ignore.
violationSeverity String 2.2 The lowest severity level that is considered a violation. Valid values are "error", "warning" and "info".
Default value is: error.
User property is: checkstyle.violationSeverity.

Parameter Details

cacheFile:

Specifies the cache file used to speed up Checkstyle on successive runs.
  • Type: java.lang.String
  • Required: No
  • Default: ${project.build.directory}/checkstyle-cachefile

checkstyleRules:

By using this property, you can specify the whole Checkstyle rules inline directly inside this pom. 
<plugin>
  ...
  <configuration>
    <checkstyleRules>
      <module name="Checker">
        <module name="FileTabCharacter">
          <property name="eachLine" value="true" />
        </module>
        <module name="TreeWalker">
          <module name="EmptyBlock"/>
        </module>
      </module>
    </checkstyleRules>
  </configuration>
  ...
  • Type: org.codehaus.plexus.configuration.PlexusConfiguration
  • Since: 2.12
  • Required: No

configLocation:

Specifies the location of the XML configuration to use.

Potential values are a filesystem path, a URL, or a classpath resource. This parameter expects that the contents of the location conform to the xml format (Checkstyle Checker module) configuration of rulesets.

This parameter is resolved as resource, URL, then file. If successfully resolved, the contents of the configuration is copied into the ${project.build.directory}/checkstyle-configuration.xml file before being passed to Checkstyle as a configuration.

There are 2 predefined rulesets.

  • config/sun_checks.xml: Sun Checks.
  • config/maven_checks.xml: Maven Source Checks.
  • Type: java.lang.String
  • Since: 2.5
  • Required: No
  • User Property: checkstyle.config.location
  • Default: config/sun_checks.xml

consoleOutput:

Output errors to console.
  • Type: boolean
  • Required: No
  • User Property: checkstyle.consoleOutput
  • Default: false

encoding:

The file encoding to use when reading the source files. If the property project.build.sourceEncoding is not set, the platform default encoding is used. Note: This parameter always overrides the property charset from Checkstyle's TreeWalker module.
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • User Property: encoding
  • Default: ${project.build.sourceEncoding}

excludes:

Specifies the names filter of the source files to be excluded for Checkstyle.
  • Type: java.lang.String
  • Required: No
  • User Property: checkstyle.excludes

failOnViolation:

Fail the build on a violation. The goal checks for the violations after logging them (if logViolationsToConsole is 'true'). Compare this to failsOnError which fails the build immediately before examining the output log.
  • Type: boolean
  • Required: No
  • User Property: checkstyle.failOnViolation
  • Default: true

failsOnError:

If this is true, and Checkstyle reported any violations or errors, the build fails immediately after running Checkstyle, before checking the log for logViolationsToConsole. If you want to use logViolationsToConsole, use failOnViolation instead of this.
  • Type: boolean
  • Required: No
  • Default: false

headerLocation:

Specifies the location of the License file (a.k.a. the header file) that can be used by Checkstyle to verify that source code has the correct license header.

You need to use ${checkstyle.header.file} in your Checkstyle xml configuration to reference the name of this header file.

For instance:

<module name="RegexpHeader"> <property name="headerFile" value="${checkstyle.header.file}"/> </module>

  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No
  • User Property: checkstyle.header.file
  • Default: LICENSE.txt

includeResources:

Whether to apply Checkstyle to resource directories.
  • Type: boolean
  • Since: 2.11
  • Required: Yes
  • User Property: checkstyle.includeResources
  • Default: true

includeTestResources:

Whether to apply Checkstyle to test resource directories.
  • Type: boolean
  • Since: 2.11
  • Required: Yes
  • User Property: checkstyle.includeTestResources
  • Default: true

includeTestSourceDirectory:

Include or not the test source directory to be used for Checkstyle.
  • Type: boolean
  • Since: 2.2
  • Required: No
  • Default: false

includes:

Specifies the names filter of the source files to be used for Checkstyle.
  • Type: java.lang.String
  • Required: Yes
  • User Property: checkstyle.includes
  • Default: **\/*.java

logViolationsToConsole:

Output the detected violations to the console.
  • Type: boolean
  • Since: 2.3
  • Required: No
  • User Property: checkstyle.console
  • Default: true

maxAllowedViolations:

The maximum number of allowed violations. The execution fails only if the number of violations is above this limit.
  • Type: int
  • Since: 2.3
  • Required: No
  • User Property: checkstyle.maxAllowedViolations
  • Default: 0

outputFile:

Specifies the path and filename to save the Checkstyle output. The format of the output file is determined by the outputFileFormat parameter.
  • Type: java.io.File
  • Required: No
  • User Property: checkstyle.output.file
  • Default: ${project.build.directory}/checkstyle-result.xml

outputFileFormat:

Specifies the format of the output to be used when writing to the output file. Valid values are "plain" and "xml".
  • Type: java.lang.String
  • Required: No
  • User Property: checkstyle.output.format
  • Default: xml

propertiesLocation:

Specifies the location of the properties file.

This parameter is resolved as URL, File then resource. If successfully resolved, the contents of the properties location is copied into the ${project.build.directory}/checkstyle-checker.properties file before being passed to Checkstyle for loading.

The contents of the propertiesLocation will be made available to Checkstyle for specifying values for parameters within the xml configuration (specified in the configLocation parameter).

  • Type: java.lang.String
  • Since: 2.5
  • Required: No
  • User Property: checkstyle.properties.location

propertyExpansion:

Allows for specifying raw property expansion information.
  • Type: java.lang.String
  • Required: No

resourceExcludes:

Specifies the names filter of the files to be excluded for Checkstyle when checking resources.
  • Type: java.lang.String
  • Since: 2.11
  • Required: No
  • User Property: checkstyle.resourceExcludes

resourceIncludes:

Specifies the names filter of the files to be used for Checkstyle when checking resources.
  • Type: java.lang.String
  • Since: 2.11
  • Required: Yes
  • User Property: checkstyle.resourceIncludes
  • Default: **/*.properties

rulesFiles:

dump file for inlined Checkstyle rules
  • Type: java.io.File
  • Required: No
  • User Property: checkstyle.output.rules.file
  • Default: ${project.build.directory}/checkstyle-rules.xml

skip:

Skip entire check.
  • Type: boolean
  • Since: 2.2
  • Required: No
  • User Property: checkstyle.skip
  • Default: false

skipExec:

Skip Checkstyle execution will only scan the outputFile.
  • Type: boolean
  • Since: 2.5
  • Required: No
  • User Property: checkstyle.skipExec
  • Default: false

sourceDirectories:

Specifies the location of the source directories to be used for Checkstyle.
  • Type: java.util.List
  • Since: 2.13
  • Required: No
  • Default: ${project.compileSourceRoots}

sourceDirectory:

Deprecated. instead use sourceDirectories
Specifies the location of the source directory to be used for Checkstyle.
  • Type: java.io.File
  • Required: No

suppressionsFileExpression:

The key to be used in the properties for the suppressions file.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • User Property: checkstyle.suppression.expression
  • Default: checkstyle.suppressions.file

suppressionsLocation:

Specifies the location of the suppressions XML file to use.

This parameter is resolved as resource, URL, then file. If successfully resolved, the contents of the suppressions XML is copied into the ${project.build.directory}/checkstyle-suppressions.xml file before being passed to Checkstyle for loading.

See suppressionsFileExpression for the property that will be made available to your Checkstyle configuration.

  • Type: java.lang.String
  • Since: 2.0-beta-2
  • Required: No
  • User Property: checkstyle.suppressions.location

testSourceDirectories:

Specifies the location of the test source directories to be used for Checkstyle.
  • Type: java.util.List
  • Since: 2.13
  • Required: No
  • Default: ${project.testCompileSourceRoots}

testSourceDirectory:

Deprecated. instead use testSourceDirectories
Specifies the location of the test source directory to be used for Checkstyle.
  • Type: java.io.File
  • Since: 2.2
  • Required: No

useFile:

If null, the Checkstyle plugin will display violations on stdout. Otherwise, a text file will be created with the violations.
  • Type: java.io.File
  • Required: No

violationIgnore:

Violations to ignore. This is a comma-separated list, each value being either a rule name, a rule category or a java package name of rule class.
  • Type: java.lang.String
  • Since: 2.13
  • Required: No
  • User Property: checkstyle.violation.ignore

violationSeverity:

The lowest severity level that is considered a violation. Valid values are "error", "warning" and "info".
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • User Property: checkstyle.violationSeverity
  • Default: error