chapter-running.asciidoc

Running Maven

This chapter focuses on the various ways in which Maven can be customized at runtime. It also documents some 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.

Maven Command Line Options

The following sections detail Maven’s command-line options.

Defining Properties

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

-D <arg>, --define

Defines a system property

Defining properties through the command line is the way most frequently used to customize 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. (For more information about referencing Maven properties, see [resource-filtering].)

Properties can also be used to activate build profiles. (For more about Maven profiles, see [profiles].)

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

-B,--batch-modeRun in non-interactive (batch) mode
...

If you need more information about the goals and parameters available from a specific Maven plugin, see Using the Maven Help Plugin.

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.

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 (lowercase) option will terminate the Maven process after printing out the version.

You’d 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

Maven home: /Users/leonardo/apache-maven
Java version: 13, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk-13.jdk/Contents/Home
Default locale: en_BR, platform encoding: UTF-8
OS name: "mac os x", version: "10.15", arch: "x86_64", family: "mac"

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.

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

Forces the use of an alternate POM file; you can also pass a path with a pom.xml file

-s,--settings <user-settings-path>

Alternate path for the user settings file

-gs, --global-settings <global-settings-path>

Alternate path for the global settings file

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 [appendix-settings-sect-encrypting-passwords].

Dealing with Failure

The following options control how Maven reacts to a build failure in the middle of a multimodule 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 for multimodule builds that are running within a continuous integration tool like Hudson or Jenkins. The -ff option is very useful for developers running interactive builds, who want to have rapid feedback during the development cycle.

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.

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.

The -X option will print a large 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. It is also useful if you are attempting to diagnose a difficult problem with a dependency or a classpath.

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.

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.

Downloading and Verifying Dependencies

The following command-line options affect the way 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

Maven is configured to just warn the end-user if an artifact’s checksum doesn’t match the downloaded artifact. This corresponds to the -c (lowercase) option, the default.

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

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 cause Maven to execute a goal or step through the lifecycle only for the project in the current directory. Maven will not attempt to build all projects in a multimodule project when you use the -N command line option.

Using Advanced Reactor Options

There are also command-line options that allow you to manipulate the way Maven will build multimodule projects:

-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

Advanced Reactor Options Example Project

The example we’ll use 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 it 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 (we’ll assume it’s examples, below), 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 Directory Structure of the Sample Multimodule Project.

Figure 1. Directory Structure of the Sample Multimodule 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 complex system. Dependencies within the Sample Multimodule Project captures the dependencies between each of these projects/modules.

Figure 2. Dependencies within the Sample Multimodule Project

If you go into the sample-parent 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, below.

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

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

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 multimodule project during a development cycle.

Assume that you are working on the multimodule 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

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

Making Project Dependents

While the -am command makes all of the projects required by a particular project in a multimodule 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 multimodule 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

Resuming a "make" build

When using --also-make, Maven will execute a subset of the larger build as shown in 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 multimodule project build. The --resume-from argument also works with --also-make-dependents.

Using the Maven Help Plugin

Throughout this book, we introduce Maven plugins, talking about Maven 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 goals active-profiles, effective-pom, and effective-settings describe a particular project and must be run in the base directory of a project. The describe goal is independent of a POM. It shows you information about a plugin or a plugin goal. The following commands provide some general information about these goals:

help:active-profiles

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

help:effective-pom

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

help:effective-settings

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

Describing a Maven Plugin

Once you start using Maven, you’ll spend a lot of time trying to get more information about Maven Plugins: How does the plugin work and what are the goals? What are its configuration parameters? You can use the help:describe goal 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 plugin.

$ mvn help:describe -Dplugin=help
...
Name: Apache Maven Help Plugin
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.
Group Id: org.apache.maven.plugins
Artifact Id: maven-help-plugin
Version: 3.2.0
Goal Prefix: help
...

As shown above, executing the describe goal with the plugin parameter prints out the Maven coordinates for the plugin, the goal prefix, and a brief description of the plugin. It also prints a a list of goals (ommitted above).

You can also obtain a more detailed list, including goal parameters, by running the help:describe goal with the parameter detail:

$ mvn help:describe -Dplugin=help -Ddetail

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