Configure Checkstyle in Multi-Module Maven Builds

Properly configuring Checkstyle is a good first step, and encapsulating the Checkstyle rules into a resusable configuration resource jar file really helps setting up centralized rules control and auditing in enterprise build environments. The next step is to automate Checkstyle execution in both developer builds and in the CI/CD environment.

There is a plugin available for Maven that allows executing Checkstyle as part of every build. The plugin can be configured to either fail or not fail the build if rule violations have been discovered. In combination with Maven’s profiles, this allows configuring Checkstyle to create a report of violations in local developer builds, and fail the build in case of rule violations when the artifact is built on a centralized continuous integration build system.

The configuration below sets up the developer build as the “default build”, which allows a developer to execute the Checkstyle checks with the “mvn clean install” they use on their local system. This developer build is configured not failing the build. It also uses the Checkstyle configuration resource file. Note that some of the configuration settings (e.g. the versions of the artifacts) are parameterized, but the configuration works the same way when no parameters, but hardcoded values, are being used.

In the example below, the “dependency” section pulls in the configuration artifact, and the “configLocation” parameter points to the Checkstyle rules configuration in the resource configuration artifact. This filename must match the actual rules filename used in the dependency.

<build>
  ...
  <plugins>
    ...
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-checkstyle-plugin</artifactId>
      <version>${mavenCheckstylePluginVersion}</version>
      <dependencies>
        <dependency>
          <groupId>${buildToolsGroupId}</groupId>
          <artifactId>${buildToolsArtifactId}</artifactId>
          <version>${buildToolsVersion}</version>
        </dependency>
      </dependencies>
      <executions>
        <execution>
          <phase>validate</phase>
          <configuration>
            <configLocation>checkstyle.xml</configLocation>
            <encoding>${project.build.sourceEncoding}</encoding>
            <consoleOutput>true</consoleOutput>
            <failOnViolation>false</failOnViolation>
            <failsOnError>false</failsOnError>
          </configuration>
          <goals>
            <goal>check</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
  ...
</build>

The CI/CD build uses a very similar plugin configuration in a profile, with the difference that the build is configured to fail in case of a rules violation:

<profiles>
  ...
  <profile>
    <id>release</id>
    ...
    <build>
      <plugins>
        ...
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
            <version>${mavenCheckstylePluginVersion}</version>
            <dependencies>
              <dependency>
                <groupId>${buildToolsGroupId}</groupId>
                <artifactId>${buildToolsArtifactId}</artifactId>
                <version>${buildToolsVersion}</version>
              </dependency>
            </dependencies>
            <executions>
              <execution>
                <phase>validate</phase>
                <configuration>
                  <configLocation>checkstyle.xml</configLocation>
                  <encoding>${project.build.sourceEncoding}</encoding>
                  <consoleOutput>true</consoleOutput>
                  <failOnViolation>true</failOnViolation>
                  <failsOnError>true</failsOnError>
                </configuration>
                <goals>
                  <goal>check</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
          ...
        </plugins>
        ...
      </build>
    ...
    </profile>
  ...
</profiles>

Maven optionally provides the functionality to create nice graphical reports by invoking “mvn site”. The Maven Checkstyle plugin can be configured to turn the results discovered in the anlysis phase into an html report that is automatically included in the project’s site report. To enable this functionality, the Checkstyle plugin is additionally added to the “reporting” section in the POM file:

<reporting>
  ...
  <plugins>
    ...
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-checkstyle-plugin</artifactId>
      <version>${mavenCheckstylePluginVersion}</version>
      <configuration>
        <configLocation>checkstyle.xml</configLocation>
        <encoding>${project.build.sourceEncoding}</encoding>
      </configuration>
      <reportSets>
        <reportSet>
          <reports>
            <report>checkstyle</report>
          </reports>
        </reportSet>
      </reportSets>
    </plugin>
    ...
  </plugins>
  ...
</reporting>

Note that the plugin configuration in the “reporting” section does not have a reference to the Checkstyle configuration resource file. The way that reporting plugins often work in Maven is that they take analysis results that are already present in the “target” directory of an artifact, and then transform them into a graphical representation. The Checkstyle plugin is no exception to this rule.

Note that this plugin needs the JXR plugin to be executed beforehand if it should provide cross-references to the source code in its reports.

Edit:See https://github.com/mbeiter/util for an example on how to configure the Maven Checkstyle Plugin as described in this post for a multi-module build.