Maven: The Complete Reference

Running Maven

Chapter 6

Introduction

This chapter focuses on the various ways in which Maven can be customized at runtime. It also provides some documentation of special features such as the ability to customize the behavior of the Maven Reactor and how to use the Maven Help plugin to obtain information about plugins and plugin goals.

6.1. Maven Command Line Options

The following sections detail Maven’s command line options.

6.1.1. Defining Properties

To define a property use the following option on the command line:

-D, --define <arg>

Defines a system property

This is the option most frequently used to customized the behavior of Maven plugins. Some examples of using the -D command line argument:

$ mvn help:describe -Dcmd=compiler:compile
$ mvn install -Dmaven.test.skip=true

Properties defined on the command line are also available as properties to be used in a Maven POM or Maven Plugin. Form more information about referencing Maven properties, see Chapter 9, Properties and Resource Filtering.

Properties can also be used to activate build profiles. For more information about Maven build profiles, see Chapter 5, Build Profiles.

6.1.2. Getting Help

To list the available command line parameters, use the following command line option:

-h, --help

Display help information

Executing Maven with this option produces the following output:

$ mvn --help

usage: mvn [options] [<goal(s)>] [<phase(s)>]

Options:
-am,--also-makeIf project list is specified, also
build projects required by the
list
-amd,--also-make-dependentsIf project list is specified, also
build projects that depend on
projects on the list
-B,--batch-modeRun in non-interactive (batch)
mode
...

If you are looking for information about the goals and parameters available from a specific Maven plugin, see Section 6.3, “Using the Maven Help Plugin”.

6.1.3. Using Build Profiles

To activate one or more build profiles from the command line, use the following option:

-P, --activate-profiles <arg>

Comma-delimited list of profiles to activate

For more information about build profiles, see Chapter 5, Build Profiles.

6.1.4. Displaying Version Information

To display Maven version information, use one of the following options on the command line:

-V, --show-version

Display version information WITHOUT stopping build

-v, --version

Display version information

Both of these options produce the same version information output, but the -v option will terminate the Maven process after printing out the version. You would use the -V option if you wanted to have the Maven version information present at the beginning of your build’s output. This can come in handy if you are running Maven in a continuous build environment and you need to know what version of Maven was used for a particular build.

Maven Version Information. 

$ mvn -v
Apache Maven 2.2.1 (r801777; 2009-08-06 14:16:01-0500)
Java version: 1.6.0_15
Java home: /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x" version: "10.6.1" arch: "x86_64" Family: "mac"

6.1.5. Running in Offline Mode

If you ever need to use Maven without having access to a network, you should use the following option to prevent any attempt to check for updates to plugins or dependencies over a network:

-o, --offline

Work offline

When running with the offline option enabled, Maven will not attempt to connect to a remote repository to retrieve artifacts.

6.1.6. Using a Custom POM or Custom Settings File

If you don’t like the pom.xml file name, the location of your user-specific Maven settings, or the default location of your global settings file, you can customize any of these things with the following options:

-f, --file <file>

Forces the use of an alternate POM file

-s,--settings <arg>

Alternate path for the user settings file

-gs, --global-settings <file>

Alternate path for the global settings file

6.1.7. Encrypting Passwords

The following commands allow you to use Maven to encrypt passwords for storage in a Maven settings file:

-emp, --encrypt-master-password <password>

Encrypt master security password

-ep, --encrypt-password <password>

Encrypt server password

Encrypting passwords is documented in Section 15.2.11, “Encrypting Passwords in Maven Settings”.

6.1.8. Dealing with Failure

The following options control how Maven reacts to a build failure in the middle of a multi-module project build:

-fae, --fail-at-end

Only fail the build afterwards; allow all non-impacted builds to continue

-ff, --fail-fast

Stop at first failure in reactorized builds

-fn, --fail-never

NEVER fail the build, regardless of project result

The -fn and -fae options are useful options for multi-module builds that are running within a continuous integration tool like Hudson. The -ff option is very useful for developers running interactive builds who want to have rapid feedback during the development cycle.

6.1.9. Controlling Maven’s Verbosity

If you want to control Maven’s logging level, you can use one of the following three command line options:

-e, --errors

Produce execution error messages

-X, --debug

Produce execution debug output

-q, --quiet

Quiet output - only show errors

The -q option only prints a message to the output if there is an error or a problem.

The -X option will print an overwhelming amount of debugging log messages to the output. This option is primarily used by Maven developers and by Maven plugin developers to diagnose problems with Maven code during development. This -X option is also very useful if you are attempting to diagnose a difficult problem with a dependency or a classpath.

The -e option will come in handy if you are a Maven developer, or if you need to diagnose an error in a Maven plugin. If you are reporting an unexpected problem with Maven or a Maven plugin, you will want to pass both the -X and -e options to your Maven process.

6.1.10. Running Maven in Batch Mode

To run Maven in batch mode use the following option:

-B, --batch-mode

Run in non-interactive (batch) mode

Batch mode is essential if you need to run Maven in a non-interactive, continuous integration environment. When running in non-interactive mode, Maven will never stop to accept input from the user. Instead, it will use sensible default values when it requires input.

6.1.11. Downloading and Verifying Dependencies

The following command line options affect the way that Maven will interact with remote repositories and how it verifies downloaded artifacts:

-C, --strict-checksums

Fail the build if checksums don’t match

-c, --lax-checksums

Warn if checksums don’t match

-U, --update-snapshots

Forces a check for updated releases and snapshots on remote repositories

If you are concerned about security, you will want to run Maven with the -C option. Maven repositories maintain an MD5 and SHA1 checksum for every artifact stored in a repository. Maven is configured to warn the end-user if an artifact’s checksum doesn’t match the downloaded artifact. Passing in the -C option will cause Maven to fail the build if it encounters an artifact with a bad checksum.

The -U option is useful if you want to make sure that Maven is checking for the latest versions of all SNAPSHOT dependencies.

6.1.12. Non-recursive Builds

There will be times when you simply want to run a Maven build without having Maven descend into all of a project’s submodules. You can do this by using the following command line option:

-N, --non-recursive

Prevents Maven from building submodules. Only builds the project contained in the current directory.

Running this will only cause Maven to execute a goal or step through the lifecycle for the project in the current directory. Maven will not attempt to build all of the projects in a multi-module project when you use the -N command line option.

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”.

figs/web/running_aro-project-dir.png

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.

figs/web/running_aro-dependencies.png

Figure 6.2. Dependencies within Sample Multi-module Project


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

6.2.2. Resuming Builds

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.

6.3. Using the Maven Help Plugin

Throughout this book, we introduce Maven plugins, talking about Maven Project Object Model (POM) files, settings files, and profiles. There are going to be times when you need a tool to help you make sense of some of the models that Maven is using and what goals are available on a specific plugin. The Maven Help plugin allows you to list active Maven profiles, display an effective POM, print the effective settings, or list the attributes of a Maven plugin.

The Maven Help plugin has four goals. The first three goals — active-profiles, effective-pom, and effective-settings — describe a particular project and must be run in the base directory of a project. The last goal — describe — is slightly more complex, showing you information about a plugin or a plugin goal. The following commands provide some general information about the four goals:

help:active-profiles

Lists the profiles (project, user, global) which are active for the build.

help:effective-pom

Displays the effective POM for the current build, with the active profiles factored in.

help:effective-settings

Prints out the calculated settings for the project, given any profile enhancement and the inheritance of the global settings into the user-level settings.

help:describe

Describes the attributes of a plugin. This need not run under an existing project directory. You must at least give the groupId and artifactId of the plugin you wish to describe.

 

6.3.1. Describing a Maven Plugin

Once you start using Maven, you’ll spend most of your time trying to get more information about Maven Plugins: How do plugins work? What are the configuration parameters? What are the goals? The help:describe goal is something you’ll be using very frequently to retrieve this information. With the plugin parameter you can specify a plugin you wish to investigate, passing in either the plugin prefix (e.g. maven-help-plugin as help) or the groupId:artifact[:version], where version is optional. For example, the following command uses the Help plugin’s describe goal to print out information about the Maven Help plugin.

$ mvn help:describe -Dplugin=help
...
Group Id:  org.apache.maven.plugins
Artifact Id: maven-help-plugin
Version: 2.0.1
Goal Prefix: help
Description:

The Maven Help plugin provides goals aimed at helping to make sense
out of the build environment. It includes the ability to view the
effective POM and settings files, after inheritance and active
profiles have been applied, as well as a describe a particular plugin
goal to give usage information.  ...

Executing the describe goal with the plugin parameter printed out the Maven coordinates for the plugin, the goal prefix, and a brief description of the plugin. While this information is helpful, you’ll usually be looking for more detail than this. If you want the Help plugin to print a full list of goals with parameters, execute the help:describe goal with the parameter full as follows:

$ mvn help:describe -Dplugin=help -Dfull
...
Group Id:  org.apache.maven.plugins
Artifact Id: maven-help-plugin
Version: 2.0.1
Goal Prefix: help
Description:

The Maven Help plugin provides goals aimed at helping to make sense
out of the build environment. It includes the ability to view the
effective POM and settings files, after inheritance and active
profiles have been applied, as well as a describe a particular plugin
goal to give usage information.

Mojos:

Goal: 'active-profiles'
Description:

Lists the profiles which are currently active for this build.

Implementation: org.apache.maven.plugins.help.ActiveProfilesMojo
Language: java

Parameters:

[0] Name: output
Type: java.io.File
Required: false
Directly editable: true
Description:

This is an optional parameter for a file destination for the output of
this mojo...the listing of active profiles per project.


[1] Name: projects
Type: java.util.List
Required: true
Directly editable: false
Description:

This is the list of projects currently slated to be built by Maven.


This mojo doesn't have any component requirements.

... removed the other goals ...

This option is great for discovering all of a plugin’s goals as well as their parameters. But sometimes this is far more information than necessary. To get information about a single goal, set the mojo parameter as well as the plugin parameter. The following command lists all of the information about the Compiler plugin’s compile goal.

$ mvn help:describe -Dplugin=compiler -Dmojo=compile -Dfull