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.1. Defining Properties
- 6.1.2. Getting Help
- 6.1.3. Using Build Profiles
- 6.1.4. Displaying Version Information
- 6.1.5. Running in Offline Mode
- 6.1.6. Using a Custom POM or Custom Settings File
- 6.1.7. Encrypting Passwords
- 6.1.8. Dealing with Failure
- 6.1.9. Controlling Maven’s Verbosity
- 6.1.10. Running Maven in Batch Mode
- 6.1.11. Downloading and Verifying Dependencies
- 6.1.12. Non-recursive Builds
The following sections detail Maven’s command line options.
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.
To list the available command line parameters, use the following command line option:
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”.
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.
To display Maven version information, use one of the following options on the command line:
Display version information WITHOUT stopping build
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"
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:
When running with the offline option enabled, Maven will not attempt to connect to a remote repository to retrieve artifacts.
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
Alternate path for the user settings file
-gs, --global-settings <file>
Alternate path for the global settings file
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”.
The following options control how Maven reacts to a build failure in the middle of a multi-module project build:
Only fail the build afterwards; allow all non-impacted builds to continue
Stop at first failure in reactorized builds
NEVER fail the build, regardless of project result
-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.
If you want to control Maven’s logging level, you can use one of the following three command line options:
Produce execution error messages
Produce execution debug output
Quiet output - only show errors
-q option only prints a message to the output if there is an error or a problem.
-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.
-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
-e options to your Maven process.
To run Maven in batch mode use the following option:
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.
The following command line options affect the way that Maven will interact with remote repositories and how it verifies downloaded artifacts:
Fail the build if checksums don’t match
Warn if checksums don’t match
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.
-U option is useful if you want to make sure that Maven is checking for the latest versions of all SNAPSHOT dependencies.
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:
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
- 6.2.1. Advanced Reactor Options Example Project
- 6.2.2. Resuming Builds
- 6.2.3. Specifying a Subset of Projects
- 6.2.4. Making a Subset of Projects
- 6.2.5. Making Project Dependents
- 6.2.6. Resuming a "make" build
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:
Resume reactor from specified project
Build specified reactor projects instead of all projects
If project list is specified, also build projects required by the list
If project list is specified, also build projects that depend on projects on the list
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:
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
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
--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
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 ...
--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-client-connector projects. If you only wanted Maven to build the
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
If you wanted to run a portion of the larger build, you would use the
--projects option with the
--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
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
-am command makes all of the projects required by a particular project in a multi-module build, the
--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
--also-make, Maven will execute a subset of the larger build as shown in Section 6.2.4, “Making a Subset of Projects”. Combining
--resume-from provides you with the ability to refine your build even further. The
--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-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
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 —
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:
Lists the profiles (project, user, global) which are active for the build.
Displays the effective POM for the current build, with the active profiles factored in.
Prints out the calculated settings for the project, given any profile enhancement and the inheritance of the global settings into the user-level settings.
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.
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.
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. ...
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:  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.  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
$ mvn help:describe -Dplugin=compiler -Dmojo=compile -Dfull