------
 Guide to Working with Multiple Modules
 ------
 Brett Porter
 Karl Heinz Marbaise
 ------
 2015-03-13
 ------

~~ 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

Guide to Working with Multiple Modules

  As seen in the introduction to the POM, Maven supports project aggregation in addition to project inheritance. This section outlines how Maven processes projects with multiple modules, and how you can work with them more effectively.

* The Reactor

  The mechanism in Maven that handles multi-module projects is referred to as the <reactor>. This part of the Maven core does the following:

    * Collects all the available modules to build

    * Sorts the projects into the correct build order

    * Builds the selected projects in order

** Reactor Sorting

  Because modules within a multi-module build can depend on each other, it is important that The reactor sorts all the projects in a way that guarantees any project is built before it is required.

  The following relationships are honoured when sorting projects:

    * a project dependency on another module in the build

    * a plugin declaration where the plugin is another modules in the build

    * a plugin dependency on another module in the build

    * a build extension declaration on another module in the build

    * the order declared in the <<<\<modules\>>>> element (if no other rule applies)

  Note that only "instantiated" references are used - <<<dependencyManagement>>> and <<<pluginManagement>>> elements will not cause a change to the reactor sort order

** Command Line Options

  No special configuration is required to take advantage of the reactor, however it is possible to customize its behavior.

  The following command line switches are available:

    * <<<--resume-from>>> - resumes a reactor the specified project (e.g. when it fails in the middle)

    * <<<--also-make>>> - build the specified projects, and any of their dependencies in the reactor

    * <<<--also-make-dependents>>> - build the specified projects, and any that depend on them

    * <<<--fail-fast>>> - the default behavior - whenever a module build fails, stop the overall build immediately

    * <<<--fail-at-end>>> - if a particular module build fails, continue the rest of the reactor and report all failed modules at the end instead

    * <<<--non-recursive>>> - do not use a reactor build, even if the current project declares modules and just build the project in the current directory

  Refer to the Maven command line interface reference for more information on these switches.

* More information

  * {{{http://books.sonatype.com/mvnex-book/reference/multimodule.html} Chapter 6. A Multi-module Project (Maven by Example)}}