Maven|Using the Maven Help Plugin

Maven Book: 2.8. Using the Maven Help Plugin

2.8. Using the Maven Help Plugin

Throughout the book, we will be introducing 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.

Note

For a conceptual overview of the POM and plugins see Chapter 3, A Simple Maven Project.

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.

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

Note

What? A Mojo? In Maven, a Plugin goal is known as a "Mojo".