------
 Multimodule Configuration
 ------
 2008-02-05
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html


Multimodule Configuration

  Configuring the Checkstyle Plugin for use within large multimodule projects
  can be done, but it requires a little setup.

  This example will use a mysterious project called <whizbang>. This is what
  the structure of that project looks like:

+-----+
whizbang
|-- pom.xml
|-- core
|   `-- pom.xml
|-- gui
|   `-- pom.xml
|-- jmx
|   `-- pom.xml
`-- src
+-----+

* Create a subproject to house the resources

  We'll start by adding another sub project that will house our common
  configuration. Let's call it <build-tools>. In it we put the resources that
  we want to include. In this example, we will add configuration files for the
  Checkstyle Plugin. Configuration files for other plugins, like the PMD
  plugin, can be included in the same subproject if you like.

+-----+
whizbang
|-- pom.xml
|-- build-tools
|   |-- src
|   |   `-- main
|   |       `-- resources
|   |           `-- whizbang
|   |               |-- checkstyle.xml
|   |               `-- LICENSE.TXT
|   `-- pom.xml
|-- core
|-- gui
|-- jmx
`-- src
+-----+

  <<Tip:>> put the resources into a subdirectory that you can ensure will be
  unique and not conflict with anyone else.

  The <<<pom.xml>>> file for <build-tools> should look like this:

+-----+
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example.whizbang</groupId>
  <artifactId>build-tools</artifactId>
  <version>1.0</version>
  <name>Build Tools</name>
</project>
+-----+
  
* Configure the other projects to use it

  Now we can include the Checkstyle configuration in the top level
  <<<pom.xml>>>.

  <<Note:>> You have to specify a plugin dependency on <<<build-tools>>> in the
  <<<\<build\>>>> element of your <<<pom.xml>>>. It will not work inside the
  <<<\<reporting\>>>> element, because <<<\<reporting\>>>> does not support
  plugin dependencies. The rest of the configuration is done in the normal way
  in the <<<\<reporting\>>>> element.

+-----+
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example.whizbang</groupId>
  <artifactId>whizbang-parent</artifactId>
  <version>1.0</version>
  <packaging>pom</packaging>
  <name>WhizBang Parent</name>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>${project.version}</version>
        <dependencies>
          <dependency>
            <groupId>com.example.whizbang</groupId>
            <artifactId>build-tools</artifactId>
            <version>1.0</version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <configLocation>whizbang/checkstyle.xml</configLocation>
          <headerLocation>whizbang/LICENSE.txt</headerLocation>
        </configuration>
      </plugin>
    </plugins>
  </reporting>
  <modules>
    <module>build-tools</module>
    <module>core</module>
    <module>jmx</module>
    <module>gui</module>
  </modules>
</project>
+-----+

  Once you are done with that, ensure that you do not include
  the Maven Checkstyle Plugin in your sub modules, as their definition and
  configuration, will override the top level parent pom's definition.

  Based on the Checkstyle Plugin configuration above, the values of
  <<<configLocation>>> and <<<headerLocation>>> will be resolved from the
  classpath. The <build-tools> JAR was included in the classpath when it was
  declared as a dependency to the plugin.

  Lastly, kick off a build of the site.

+-----+
mvn site
+-----+

  Every sub project will now use the same Checkstyle setup and configuration.