6.2. Using Advanced Reactor Options
Starting with the Maven 2.1 release, there are new Maven command line
options which allow you to manipulate the way that Maven will build
multimodule projects. These new options are:
-
-rf, --resume-from
-
Resume reactor from specified project
-
-pl, --projects
-
Build specified reactor projects instead of all projects
-
-am, --also-make
-
If project list is specified, also build projects required by the
list
-
-amd, --also-make-dependents
-
If project list is specified, also build projects that depend on
projects on the list
6.2.1. Advanced Reactor Options Example Project
The example in this section is a skeleton of a complex multimodule
project that is used to illustrate the advanced reactor options. While
it is possible to read this section without the example code, you
might want to download the example code and follow along,
experimenting with the various options as you learn how to use the
advanced reactor options. This section’s example project may be
downloaded with the book’s example code at:
http://books.sonatype.com/mvnref-book/mvnref-examples.zip
Unzip this archive in any directory, and then go to the ch-running/
directory. There you will see a directory named sample-parent/. All
of the examples in this section will be executed from the
examples/ch-running/sample-parent/ directory in the examples
distribution. The sample-parent/ directory contains the multimodule
project structure shown in Figure 6.1, “Directory Structure of Sample Multi-module Project”.
This project approximates the structure of a real-world enterprise
project: the sample-model
project contains a set of foundational
model objects used throughout the system, the sample-util
project
would contain utility code, the sample-persist
project would contain
logic that deals with persisting objects to a database, and the other
projects would all be combined to produce the various GUI and
Web-based interfaces that comprise a very complex
system. Figure 6.2, “Dependencies within Sample Multi-module Project” captures the dependencies between
each of these sample modules.
If you go into the sample-parent/ project directory and run mvn
clean
, you will see that the Maven Reactor reads all of the project
dependencies and comes up with the following build order for these
projects as shown in Order of Project Builds in Maven Reactor.
Order of Project Builds in Maven Reactor.
[INFO] Reactor build order:
[INFO] sample-parent
[INFO] sample-model
[INFO] sample-persist
[INFO] sample-services
[INFO] sample-util
[INFO] sample-security
[INFO] sample-admin-webapp
[INFO] sample-webapp
[INFO] sample-rest
[INFO] sample-client-connector
[INFO] sample-gui
[INFO] sample-admin-gui
The -rf
or --resume-from
option can come in handy if you want to
tell the Maven Reactor to resume a build from a particular
project. This can be useful if you are working with a large
multimodule project and you want to restart a build at a particular
project in the Reactor without running through all of the projects
that precede it in the build order.
Assume that you are working on the multi-module project with the build
order shown in Order of Project Builds in Maven Reactor and that your build ran
successfully up until Maven encountered a failing unit test in
sample-client-connector
. With the -rf
option, you can fix the unit
test in simple-client-connector
and then run mvn -rf
sample-client-connect
from the sample-parent/ directory to resume
the build with the final three projects.
$ mvn --resume-from sample-client-connector install
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] sample-client-connector
[INFO] sample-gui
[INFO] sample-admin-gui
...
6.2.3. Specifying a Subset of Projects
The -pl
or --projects
option allows you to select a list of
projects from a multimodule project. This option can be useful if you
are working on a specific set of projects, and you’d rather not wait
for a full build of a multi-module project during a development cycle.
Assume that you are working on the multi-module project with the build
order shown in Order of Project Builds in Maven Reactor and that you are a developer
focused on the sample-rest
and sample-client-connector
projects. If you only wanted Maven to build the sample-rest
and
sample-client-connector
project, you would use the following syntax
from the sample-parent/ directory:
$ mvn --projects sample-client-connector,sample-rest install
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] sample-rest
[INFO] sample-client-connector
6.2.4. Making a Subset of Projects
If you wanted to run a portion of the larger build, you would use the
-pl
or --projects
option with the -am
or --also-make
option. When you specify a project with the -am
option, Maven will
build all of the projects that the specified project depends upon
(either directly or indirectly). Maven will examine the list of
projects and walk down the dependency tree, finding all of the
projects that it needs to build.
If you are working on the multi-module project with the build order
shown in Order of Project Builds in Maven Reactor and you were only interested in
working on the sample-services
project, you would run mvn -pl
simple-services -am
to build only those projects
$ mvn --projects sample-services --also-make install
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] sample-parent
[INFO] sample-model
[INFO] sample-persist
[INFO] sample-services
6.2.5. Making Project Dependents
While the -am
command makes all of the projects required by a
particular project in a multi-module build, the -amd
or
--also-make-dependents
option configures Maven to build a project
and any project that depends on that project. When using
--also-make-dependents
, Maven will examine all of the projects in
our reactor to find projects that depend on a particular project. It
will automatically build those projects and nothing else.
If you are working on the multi-module project with the build order
shown in Order of Project Builds in Maven Reactor and you wanted to make sure that
your changes to sample-services
did not introduce any errors into
the projects that directly or indirectly depend on sample-services
,
you would run the following command:
$ mvn --projects sample-services --also-make-dependents install
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] sample-services
[INFO] sample-admin-webapp
[INFO] sample-webapp
[INFO] sample-rest
6.2.6. Resuming a "make" build
When using --also-make
, Maven will execute a subset of the larger
build as shown in Section 6.2.4, “Making a Subset of Projects”. Combining --project
,
--also-make
, and --resume-from
provides you with the ability to
refine your build even further. The -rf
or --resume-from
resumes
the build from a specific point in the Reactor build order.
$ mvn --projects sample-webapp --also-make \
--resume-from sample-services install
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] sample-services
[INFO] sample-util
[INFO] sample-security
[INFO] sample-webapp
In this example, the build is resumed from sample-services
which
omits the sample-persist
and sample-model
projects from the
build. If you are focused on individual components and you need to
accelerate your build times, using these advanced reactor options
together is a great way to skip portions of your large multi-module
project build. The --resume-from
argument also works with
--also-make-dependents
.