------
 Preparing the Build Environment
 ------
 Benjamin Bentmann
 ------
 2008-08-17
 ------

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

Preparing the Build Environment

  In general, the plugin assumes that the projects to build are unrelated to one other such that their build order does
  not matter. However, you might sometimes want to ensure that certain projects are build before others. As a
  motivation, imagine that a project performs some kind of common setup for the other projects, e.g. installing utility
  artifacts into the local repository.

  Starting with plugin version 1.3, you can declare a group of setup projects that must be run before all the other
  projects by means of the parameter <<<\<setupIncludes\>>>> as shown in the following example:

+----
<project>
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-invoker-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <setupIncludes>
            <setupInclude>utility-plugin/pom.xml</setupInclude>
          </setupIncludes>
          <pomIncludes>
            <pomInclude>*/pom.xml</pomInclude>
          </pomIncludes>
        </configuration>
        <executions>
          <execution>
            <id>integration-test</id>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
+----

  This tells the plugin that the project <<<utility-plugin/pom.xml>>> must be run before the other projects selected by
  the pattern <<<*/pom.xml>>>. Please note that although the pattern <<<*/pom.xml>>> also matches the path
  <<<utility-plugin/pom.xml>>>, this project will not be run twice. In other words, any project selected by both
  <<<\<setupIncludes\>>>> and <<<\<pomIncludes\>>>> will only be run once, namely during the setup phase.

  The build order of several such setup projects is still undefined. So if the setup projects have inter-dependencies
  that require a certain build order, you should group them by an aggregator POM and feed that into the Invoker Plugin
  such that the correct build order will be determined by Maven's multi-module reactor.