This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven-help-plugin.git
commit ab5c793ab75d5bbb2112e188e9e0f467488bb82b Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Tue Nov 17 19:24:58 2026 +0000 Refresh the site documentation around common tasks Documents the list-dependency-types, list-lifecycle-phases and list-packaging goals, which the pages never mentioned. Sample output comes from a current build; the 3.0.0 upgrade note is gone. --- .../markdown/examples/describe-configuration.md | 287 +++++++++------------ src/site/markdown/index.md | 81 ++++-- src/site/markdown/usage.md | 187 ++++++++++---- src/site/site.xml | 5 +- 4 files changed, 318 insertions(+), 242 deletions(-) diff --git a/src/site/markdown/examples/describe-configuration.md b/src/site/markdown/examples/describe-configuration.md index 5a0f18d..27be837 100644 --- a/src/site/markdown/examples/describe-configuration.md +++ b/src/site/markdown/examples/describe-configuration.md @@ -1,10 +1,10 @@ --- -title: Configuring Describe Goal +title: Configure the describe goal author: - John Casey - Maria Odea Ching - Vincent Siveton -date: 2010-01-21 +date: 2026-11-17 --- <!-- @@ -26,225 +26,170 @@ specific language governing permissions and limitations under the License. --> -# Configuring Describe Goal -Below are other configuration examples for the [`help:describe`](../describe-mojo.html) goal. +# Configure the describe goal -## The `plugin` Parameter +The [`help:describe`](../describe-mojo.html) goal answers two kinds of questions: what a plugin or goal does and which +parameters it takes, and what Maven runs for a lifecycle phase. This page shows its options. -The `plugin` parameter is meant to provide two things: convenience and prefix-based access. +## Choose a plugin with `plugin` -The convenience comes when specifying a plugin by `groupId:artifactId`, or by `groupId:artifactId:version`. Where the more traditional specification of separate fields would mean specifying this: +The `plugin` parameter accepts a plugin prefix, or coordinates in the form `groupId:artifactId[:version]`: ```bash -# mvn help:describe -DgroupId=org.somewhere -DartifactId=some-plugin -Dversion=0.0.0 +mvn help:describe -Dplugin=help +mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin +mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.6.0 ``` -the use of the plugin parameter allows this: +Without a version, the goal describes the latest release. The separate `groupId`, `artifactId` and `version` +parameters do the same as the coordinates form: ```bash -# mvn help:describe -Dplugin=org.somewhere:some-plugin:0.0.0 +mvn help:describe -DgroupId=org.apache.maven.plugins -DartifactId=maven-help-plugin ``` -Here is an example to describe the Help plugin: +The output starts with the plugin's coordinates and prefix, then lists its goals: -```bash -# mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin -``` +```text +[INFO] org.apache.maven.plugins:maven-help-plugin:3.6.0 -**Note**: `version` is always optional here. +Name: Apache Maven Help Plugin +Description: The Maven Help plugin provides goals aimed at helping to make + sense out of the build environment. ... +Group Id: org.apache.maven.plugins +Artifact Id: maven-help-plugin +Version: 3.6.0 +Goal Prefix: help -On the other hand, the plugin parameter also offers the option to specify a plugin by its prefix, like this: +This plugin has 11 goals: -```bash -# mvn help:describe -Dplugin=help -``` +help:active-profiles + Description: Displays a list of the profiles which are currently active for + this build. -## The `goal` Parameter +help:all-profiles + Description: Displays a list of available profiles under the current + project. ... +... +``` -You can use the `goal` parameter of the `describe` goal to show or display relative information about a particular goal of the plugin you specified. +## Describe one goal with `goal` -For example, when you execute the following command: +Add the `goal` parameter to describe a single goal of the plugin: -```sh -# mvn help:describe -Dgoal=describe -DgroupId=org.apache.maven.plugins -DartifactId=maven-help-plugin +```bash +mvn help:describe -Dplugin=help -Dgoal=effective-pom ``` -This would display brief information about the `describe` goal only. +## Show more or less with `detail` and `minimal` -## The `cmd` Parameter +Add `-Ddetail` to list each goal's parameters, with their descriptions, default values and the user property +you can set them with on the command line. This is usually what you want when you configure a goal: -You can also ask for a single Maven goal, phase, or lifecycle: +```bash +mvn help:describe -Dplugin=compiler -Dgoal=compile -Ddetail +``` -```sh -# mvn -help +Add `-Dminimal` to print only the plugin's coordinates and description, without its goals: -usage: mvn [options] [<goal(s)>] [<phase(s)>] -... +```bash +mvn help:describe -Dplugin=help -Dminimal ``` -The following are some examples: +```text +[INFO] org.apache.maven.plugins:maven-help-plugin:3.6.0 -```sh -# mvn help:describe -Dcmd=clean -... -[INFO] [help:describe] -[INFO] 'clean' is a lifecycle with the following phases: -* pre-clean: NOT DEFINED -* clean: org.apache.maven.plugins:maven-clean-plugin:clean -* post-clean: NOT DEFINED -... +Name: Apache Maven Help Plugin +Description: The Maven Help plugin provides goals aimed at helping to make + sense out of the build environment. ... +Group Id: org.apache.maven.plugins +Artifact Id: maven-help-plugin +Version: 3.6.0 +Goal Prefix: help + +For more information, run 'mvn help:describe [...] -Ddetail' ``` -```shell -# mvn help:describe -Dcmd=compile -... -[INFO] [help:describe] -[INFO] 'compile' is a phase corresponding to this plugin: -org.apache.maven.plugins:maven-compiler-plugin:compile +## Describe a phase or goal with `cmd` -It is a part of the lifecycle for the POM packaging 'jar'. This lifecycle includes the following phases: -* validate: NOT DEFINED -* initialize: NOT DEFINED -* generate-sources: NOT DEFINED -* process-sources: NOT DEFINED -* generate-resources: NOT DEFINED -* process-resources: org.apache.maven.plugins:maven-resources-plugin:resources -* compile: org.apache.maven.plugins:maven-compiler-plugin:compile -* process-classes: NOT DEFINED -* generate-test-sources: NOT DEFINED -* process-test-sources: NOT DEFINED -* generate-test-resources: NOT DEFINED -* process-test-resources: org.apache.maven.plugins:maven-resources-plugin:testResources -* test-compile: org.apache.maven.plugins:maven-compiler-plugin:testCompile -* process-test-classes: NOT DEFINED -* test: org.apache.maven.plugins:maven-surefire-plugin:test -* package: org.apache.maven.plugins:maven-jar-plugin:jar -* pre-integration-test: NOT DEFINED -* integration-test: NOT DEFINED -* post-integration-test: NOT DEFINED -* verify: NOT DEFINED -* install: org.apache.maven.plugins:maven-install-plugin:install -* deploy: org.apache.maven.plugins:maven-deploy-plugin:deploy -... -``` +The `cmd` parameter takes a lifecycle phase or a plugin goal in the form `prefix:goal`, as you would pass them to `mvn`. The answer reflects your project, so for a phase it shows the plugin goals bound by the project's +packaging, with their versions. -```shell -# mvn help:describe -Dcmd=compiler:compile -... -[INFO] 'compiler:compile' is a plugin goal (aka mojo). -Mojo: 'compiler:compile' -compiler:compile - Description: Compiles application sources - Deprecated. No reason given +For a phase, the goal shows the plugin goal it runs and the whole lifecycle it belongs to: -For more information, run 'mvn help:describe [...] -Ddetail' -... +```bash +mvn help:describe -Dcmd=compile ``` -## The `minimal`, and `detail` Parameters +```text +[INFO] 'compile' is a phase corresponding to this plugin: +org.apache.maven.plugins:maven-compiler-plugin:3.15.0:compile -If you want to display less or more detailed information, you can use the `minimal`, or `detail` parameters. +It is a part of the lifecycle for the POM packaging 'jar'. This lifecycle includes the following phases: +* validate: Not defined +* initialize: Not defined +* generate-sources: Not defined +* process-sources: Not defined +* generate-resources: Not defined +* process-resources: org.apache.maven.plugins:maven-resources-plugin:3.4.0:resources +* compile: org.apache.maven.plugins:maven-compiler-plugin:3.15.0:compile +* process-classes: Not defined +* generate-test-sources: Not defined +* process-test-sources: Not defined +* generate-test-resources: Not defined +* process-test-resources: org.apache.maven.plugins:maven-resources-plugin:3.4.0:testResources +* test-compile: org.apache.maven.plugins:maven-compiler-plugin:3.15.0:testCompile +* process-test-classes: Not defined +* test: org.apache.maven.plugins:maven-surefire-plugin:3.5.4:test +* prepare-package: Not defined +* package: org.apache.maven.plugins:maven-jar-plugin:3.5.0:jar +* pre-integration-test: Not defined +* integration-test: Not defined +* post-integration-test: Not defined +* verify: Not defined +* install: org.apache.maven.plugins:maven-install-plugin:3.1.4:install +* deploy: org.apache.maven.plugins:maven-deploy-plugin:3.1.4:deploy +``` -The `minimal` parameter adds a minimal list of information: +`Not defined` means no plugin goal is bound to that phase by default; your POM can still bind one there. -```shell -# mvn help:describe -Dplugin=help -Dminimal=true -... -[INFO] [help:describe] -[INFO] org.apache.maven.plugins:maven-help-plugin:2.1-SNAPSHOT -Group Id: org.apache.maven.plugins -Artifact Id: maven-help-plugin -Version: 2.1-SNAPSHOT -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. +The `clean` phase belongs to its own lifecycle: -For more information, run 'mvn help:describe [...] -Ddetail' -... +```bash +mvn help:describe -Dcmd=clean ``` -If you don't provide a parameter, a list is added with the mojos of the plugin and their -descriptions: -```sh -# mvn help:describe -Dplugin=help -... -[INFO] org.apache.maven.plugins:maven-help-plugin:2.1-SNAPSHOT -Group Id: org.apache.maven.plugins -Artifact Id: maven-help-plugin -Version: 2.1-SNAPSHOT -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. +```text +[INFO] 'clean' is a phase within the 'clean' lifecycle, which has the following phases: +* pre-clean: Not defined +* clean: org.apache.maven.plugins:maven-clean-plugin:3.2.0:clean +* post-clean: Not defined +``` -This plugin has 9 goals: +For a plugin goal, the output matches `-Dplugin=... -Dgoal=...`: -help:active-profiles - Description: Displays a list of the profiles which are currently active for - this build. - Deprecated. No reason given +```bash +mvn help:describe -Dcmd=compiler:compile +``` -help:all-profiles - Description: Displays a list of available profiles under the current - project. - Note: it will list all profiles for a project. If a profile comes up with a - status inactive then there might be a need to set profile activation - switches/property. - Deprecated. No reason given - -help:describe - Description: Displays a list of the attributes for a Maven Plugin and/or - Mojo (Maven plain Old Java Object). - Deprecated. No reason given - -help:effective-pom - Description: Displays the effective POM as an XML for this build, with the - active profiles factored in. - Deprecated. No reason given - -help:effective-settings - Description: Displays the calculated settings as XML for this project, - given any profile enhancement and the inheritance of the global settings - into the user-level settings. - Deprecated. No reason given - -help:evaluate - Description: Evaluates Maven expressions given by the user in an - interactive mode. - Deprecated. No reason given - -help:help - Description: Display help information on maven-help-plugin. - Call - mvn help:help -Ddetail=true -Dgoal=<goal-name> - to display parameter details. - Deprecated. No reason given - -help:system - Description: Displays a list of the platform details like system properties - and environment variables. - Deprecated. No reason given +```text +[INFO] 'compiler:compile' is a plugin goal (aka mojo). +Mojo: 'compiler:compile' +compiler:compile + Description: Compiles application sources. By default uses the javac + compiler of the JDK used to execute Maven. This can be overwritten through + Toolchains or parameter compilerId. See also: javac Command For more information, run 'mvn help:describe [...] -Ddetail' -... ``` -The `detail` parameter also displays information about the goal's implementation, their parameters and component requirements, among others. - -```sh -# mvn help:describe -Dplugin=help -Ddetail=true -``` +The versions in these samples depend on your Maven version and your POM. -## The `output` Parameter +## Write to a file with `output` -This `describe` goal can use the optional `output` parameter to redirect the output to a file. Here is an example of that: +The `output` parameter writes the description to a file instead of the console: -```sh -# mvn help:describe -Dplugin=help -Ddetail=true -Doutput=/path/to/file +```bash +mvn help:describe -Dplugin=compiler -Ddetail -Doutput=compiler-plugin.txt ``` diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index f37d5f6..184c295 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -3,7 +3,7 @@ title: Introduction author: - Maria Odea Ching - Vincent Siveton -date: 2013-07-22 +date: 2026-11-17 --- <!-- @@ -26,34 +26,73 @@ under the License. --> # Apache Maven Help Plugin -The Maven Help Plugin is used to get relative information about a project or the system. It can be used to get a description of a particular plugin, including the plugin's goals with their parameters and component requirements, the effective POM and effective settings of the current build, and the profiles applied to the current project being built. -## Goals Overview +When a build does something unexpected, the Help Plugin shows you what Maven actually sees: +the final POM after inheritance and profiles, the merged settings, the active profiles, the +value of any property, and what a plugin goal does and which parameters it takes. -The Help Plugin has 8 goals: +You don't need to add the plugin to your POM. Run a goal from your project directory: -- [help:active-profiles](./active-profiles-mojo.html) lists the profiles which are currently active for the build. -- [help:all-profiles](./all-profiles-mojo.html) lists the available profiles under the current project. -- [help:describe](./describe-mojo.html) describes the attributes of a Plugin and/or a Mojo (Maven plain Old Java Object). -- [help:effective-pom](./effective-pom-mojo.html) displays the effective POM as an XML for the current build, with the active profiles factored in. If `verbose`, a comment is added to each XML element describing the origin of the line. -- [help:effective-settings](./effective-settings-mojo.html) displays the calculated settings as an XML for the project, given any profile enhancement and the inheritance of the global settings into the user-level settings. -- [help:evaluate](./evaluate-mojo.html) evaluates Maven expressions given by the user in an interactive mode. -- [help:help](./help-mojo.html) Display help information for the maven-help-plugin itself. -- [help:system](./system-mojo.html) displays a list of the platform details like system properties and environment variables. -## Major Version Upgrade to version 3.0.0 +```bash +mvn help:effective-pom +``` -Please note that the goal `expressions` has been completely removed from the plugin. All the Maven expressions that are supported as plugin parameters are available in the Javadoc of the [`PluginParameterExpressionEvaluator`](/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html) class. +## What do you want to know? -## Usage +| Question | Command | +|---|---| +| What does my POM look like after inheritance, profiles and interpolation? | `mvn help:effective-pom` | +| Where does that value in the effective POM come from? | `mvn help:effective-pom -Dverbose` | +| Which profiles are active, and which ones exist? | `mvn help:active-profiles`, `mvn help:all-profiles` | +| What is the value of a property or expression? | `mvn help:evaluate -Dexpression=project.version -q -DforceStdout` | +| Which settings, mirrors and servers is Maven using? | `mvn help:effective-settings` | +| What goals and parameters does a plugin have? | `mvn help:describe -Dplugin=compiler -Ddetail` | +| Which plugin runs in a given phase? | `mvn help:describe -Dcmd=package` | +| Which lifecycle phases, packagings and dependency types exist? | `mvn help:list-lifecycle-phases`, `mvn help:list-packaging`, `mvn help:list-dependency-types` | +| Which JVM, system properties and environment variables does Maven see? | `mvn help:system` | -General instructions on how to use the Help Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. +The [usage page](./usage.html) walks through each of these with sample output. -In case you still have questions regarding the plugin's usage, please feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). +## Goals -If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are wel [...] +The plugin has 11 goals. -## Examples +Inspect the build: -To better understand some usages of the Help Plugin, see the following example(s): +- [`help:effective-pom`](./effective-pom-mojo.html) displays the effective POM of each project in the build, or of any + artifact with `-Dartifact=groupId:artifactId[:version]`. +- [`help:effective-settings`](./effective-settings-mojo.html) displays the settings after the global and user + `settings.xml` files are merged. Passwords are hidden unless you add `-DshowPasswords`. +- [`help:active-profiles`](./active-profiles-mojo.html) lists the profiles that are active for each project, and where + each one is defined. +- [`help:all-profiles`](./all-profiles-mojo.html) lists every profile available to the project, active or not. +- [`help:evaluate`](./evaluate-mojo.html) prints the value of a Maven expression, either one given on the command line or + interactively. +- [`help:system`](./system-mojo.html) lists the system properties and environment variables. -- [Configuring Describe Goal](./examples/describe-configuration.html) +Explore plugins and lifecycles: + +- [`help:describe`](./describe-mojo.html) describes a plugin, one of its goals, or a lifecycle phase. +- [`help:list-lifecycle-phases`](./list-lifecycle-phases-mojo.html) lists the phases of the `clean`, `default` and `site` + lifecycles. +- [`help:list-packaging`](./list-packaging-mojo.html) lists the known packaging types and the plugin goals bound to each + phase. +- [`help:list-dependency-types`](./list-dependency-types-mojo.html) lists the known dependency types with their file + extension and classifier. +- [`help:help`](./help-mojo.html) displays help for this plugin itself. + +Every goal except `help:help` accepts `-Doutput=<file>` to write its result to a file instead of the console. + +## Requirements + +The plugin needs Maven 3.9.0 or later and Java 8 or later. You don't need to declare it in your POM: Maven resolves +the `help` prefix to the latest release, unless your POM pins a version. To choose the version yourself, +call the goal by its full coordinates, for example `mvn org.apache.maven.plugins:maven-help-plugin:3.6.0:effective-pom`. + +## Getting help + +- Ask questions on the [user mailing list](./mailing-lists.html); its archive may already hold the answer. +- Report bugs and request features in the [issue tracker](./issue-management.html). A small project that reproduces + the problem gets it fixed fastest. +- Contributions are welcome: see the [source repository](./scm.html) and the + [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html). diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md index 8296eda..828dc1c 100644 --- a/src/site/markdown/usage.md +++ b/src/site/markdown/usage.md @@ -4,7 +4,7 @@ author: - John Casey - Maria Odea Ching - Vincent Siveton -date: 2010-01-21 +date: 2026-11-17 --- <!-- @@ -26,103 +26,192 @@ specific language governing permissions and limitations under the License. --> + # Usage -Below are the different goals and the minimalist configurations of the Help Plugin. +You can run every goal from the command line without configuring the plugin in your POM. Goals that inspect a project +run against the POM in the current directory; add `-f path/to/pom.xml` to point at another one. Every goal except +`help:help` accepts `-Doutput=<file>` to write its result to a file instead of the console. + +## See the effective POM + +Your POM is only part of the model Maven builds from: it inherits from parent POMs and the super POM, imports BOMs, +applies active profiles and interpolates properties. The [`effective-pom`](./effective-pom-mojo.html) goal shows the +result for each project in the build: -## The `help:active-profiles` Goal +```bash +mvn help:effective-pom +``` -The [`active-profiles`](./active-profiles-mojo.html) goal is used to discover which profiles have been applied to the projects currently being built. For each project in the build session, it will output a list of profiles which have been applied to that project, along with the source of the profile (POM, `settings.xml` or `profiles.xml`). +To find out where a value comes from, add `-Dverbose`. Each element then carries a comment with the POM and line +that set it: + +```xml +<project xmlns="http://maven.apache.org/POM/4.0.0" ...> + <modelVersion>4.0.0</modelVersion> <!-- com.example:demo:1.0.0, line 1 --> + <groupId>com.example</groupId> <!-- com.example:demo:1.0.0, line 1 --> + <artifactId>demo</artifactId> <!-- com.example:demo:1.0.0, line 1 --> + <version>1.0.0</version> <!-- com.example:demo:1.0.0, line 1 --> + <repositories> + <repository> + <snapshots> + <enabled>false</enabled> <!-- org.apache.maven:maven-model-builder:3.9.16:super-pom, line 33 --> + </snapshots> +``` -You can execute this goal using the following command: +To inspect the effective POM of a published artifact instead, add `-Dartifact`. The goal still has to run inside a +project directory: ```bash -# mvn help:active-profiles +mvn help:effective-pom -Dartifact=org.apache.commons:commons-lang3:3.17.0 ``` -**Note**: you could also use the `output` parameter to redirect output to a file. +Leave out the version to use the latest release. + +## Check which profiles apply + +The [`active-profiles`](./active-profiles-mojo.html) goal lists the profiles that are active for each project, and +where each one is defined. Use it with the same `-P` options and properties you build with: -## The `help:all-profiles` Goal +```bash +mvn help:active-profiles -Pci +``` -The [`all-profiles`](./all-profiles-mojo.html) goal is used to discover all available profiles under the current project. +```text +Active Profiles for Project 'com.example:demo:jar:1.0.0': -You can execute this goal using the following command: +The following profiles are active: + + - ci (source: com.example:demo:1.0.0) +``` + +The [`all-profiles`](./all-profiles-mojo.html) goal lists every profile available to the project, from the POM and +from `settings.xml`, and whether it is active: ```bash -# mvn help:all-profiles +mvn help:all-profiles +``` + +```text +[INFO] Listing Profiles for Project: com.example:demo:jar:1.0.0 + Profile Id: dev (Active: true, Source: pom) + Profile Id: ci (Active: false, Source: pom) ``` -**Note**: you could also use the `output` parameter to redirect output to a file. +A profile reported as inactive may need an activation property or a `-P` option. See the +[introduction to build profiles](https://maven.apache.org/guides/introduction/introduction-to-profiles.html). -## The `help:describe` Goal +In a multi-module build, `effective-pom`, `active-profiles` and `all-profiles` report on each module. Use `-pl` to +narrow them to one module, for example `mvn help:active-profiles -pl core`. -The [`describe`](./describe-mojo.html) goal is used to discover information about Maven plugins. Given either a `plugin` or a `groupId`, an `artifactId` and optionally a `version`, the goal will lookup that plugin and output details about it. If the user also specifies which `goal` to describe, the `describe` goal will limit output to the details of that goal, including parameters. +## Read a property or expression -You can execute this goal using the following command: +The [`evaluate`](./evaluate-mojo.html) goal prints the value of a Maven expression. In a script, combine it with +`-q` and `-DforceStdout` so that only the value is printed: ```bash -# mvn help:describe -DgroupId=org.somewhere -DartifactId=some-plugin -Dversion=0.0.0 +VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout) +echo "$VERSION" ``` -**Note**: you could also use the `output` parameter to redirect output to a file. +Write the expression without the surrounding `${...}`. Any property works, as do model paths such as +`project.build.directory` or `project.parent.version`. An expression that resolves to nothing prints +`null object or invalid expression`, and a malformed one prints nothing. In both cases the command exits with status 0, +so check the value in your script. -Refer to [Configuring Describe Goal](./examples/describe-configuration.html) for more information about its configuration. +Add `-Dartifact=groupId:artifactId[:version]` to evaluate the expression against a published artifact instead of the +current project. -## The `help:effective-pom` Goal +Without `-Dexpression`, the goal prompts for expressions one at a time until you enter `0`: -The [`effective-pom`](./effective-pom-mojo.html) goal is used to make visible the POM that results from the application of interpolation, inheritance and active profiles. It provides a useful way of removing the guesswork about just what ends up in the POM that Maven uses to build your project. It will iterate over all projects in the current build session, printing the effective POM for each. +```text +[INFO] Enter the Maven expression i.e. ${project.groupId} or 0 to exit?: +${project.artifactId} +[INFO] +demo +``` -You can execute this goal using the following command: +The interactive mode needs Maven to run in interactive mode, so it does not work with `-B` (batch mode). It always +prints to the console and ignores `-Doutput`. + +The expressions available to plugin parameters are listed in the Javadoc of +[`PluginParameterExpressionEvaluator`](/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html). + +## Check your settings + +The [`effective-settings`](./effective-settings-mojo.html) goal shows the settings Maven actually uses: the global +`settings.xml` merged with your user `settings.xml`, where the user file wins. This is the place to check mirrors, +servers, proxies and the local repository path: ```bash -# mvn help:effective-pom +mvn help:effective-settings ``` -**Note**: you could also use the `output` parameter to redirect output to a file. +Passwords are masked. Add `-DshowPasswords` to print them, and keep that output out of build logs. -## The `help:effective-settings` Goal +## Learn about a plugin -The [`effective-settings`](./effective-settings-mojo.html) goal is used to view the settings that Maven actually uses to run the build. These settings are a result of merging the global file with the user's file, with the user's file taking precedence. +The [`describe`](./describe-mojo.html) goal shows the goals of a plugin and, with `-Ddetail`, their parameters. Name the +plugin by its prefix or by its coordinates: -You can execute this goal using the following command: +```bash +mvn help:describe -Dplugin=compiler +mvn help:describe -Dplugin=org.apache.maven.plugins:maven-compiler-plugin -Dgoal=compile -Ddetail +``` + +It also tells you what runs in a lifecycle phase: ```bash -# mvn help:effective-settings +mvn help:describe -Dcmd=package ``` -**Note**: you could also use the `output` parameter to redirect output to a file. +[Configure the describe goal](./examples/describe-configuration.html) covers all of its options with sample output. + +## List lifecycles, packagings and dependency types -## The `help:system` Goal +Three goals list what your Maven installation knows about. They don't need a project. -The [`system`](./system-mojo.html) goal is used to view the system information like system properties and environment variables. +- [`list-lifecycle-phases`](./list-lifecycle-phases-mojo.html) lists the phases of each lifecycle. +- [`list-packaging`](./list-packaging-mojo.html) lists each packaging type with the plugin goals bound to its phases. +- [`list-dependency-types`](./list-dependency-types-mojo.html) lists each dependency `type` with its file extension and + classifier, and whether it is added to the classpath. -You can execute this goal using the following command: +For example: ```bash -# mvn help:system +mvn help:list-dependency-types ``` -**Note**: you could also use the `output` parameter to redirect output to a file. +```text +Maven Dependency Types defined: -## The `help:evaluate` Goal +ejb-client + - Extension: *.jar + - Classifier: client + - Added to classpath -You could use this interactive goal to evaluate some Maven expressions. To do it, just call the [help:evaluate](./evaluate-mojo.html) goal: +jar + - Extension: *.jar + - Added to classpath -```shell -# mvn help:evaluate -Dartifact=org.apache.maven.plugins:maven-help-plugin -... -[INFO] [help:evaluate] -[INFO] Enter the Maven expression i.e. ${project.groupId} or 0 to exit?: -${project.artifactId} -[INFO] -maven-help-plugin -[INFO] Enter the Maven expression i.e. ${project.groupId} or 0 to exit?: -${project.none} -[INFO] -null object or invalid expression +pom + - Extension: *.pom + +test-jar + - Extension: *.jar + - Classifier: tests + - Added to classpath ... ``` -The `artifact` parameter refers to ask expressions on the artifact POM. If omitted, the evaluate goal uses the current pom. +See the [introduction to the build lifecycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) +for what the phases mean. -You could ask for all Maven expressions listed in the Javadoc of the [`PluginParameterExpressionEvaluator`](/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html) class. +## Inspect the environment + +The [`system`](./system-mojo.html) goal lists the system properties and environment variables that Maven sees. It +helps when a build behaves differently on another machine or in CI: + +```bash +mvn help:system +``` diff --git a/src/site/site.xml b/src/site/site.xml index 5933183..a1644d4 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -31,6 +31,9 @@ under the License. <item name="help:effective-pom" href="effective-pom-mojo.html"/> <item name="help:effective-settings" href="effective-settings-mojo.html"/> <item name="help:evaluate" href="evaluate-mojo.html"/> + <item name="help:list-dependency-types" href="list-dependency-types-mojo.html"/> + <item name="help:list-lifecycle-phases" href="list-lifecycle-phases-mojo.html"/> + <item name="help:list-packaging" href="list-packaging-mojo.html"/> <item name="help:system" href="system-mojo.html"/> <item name="help:help" href="help-mojo.html"/> </item> @@ -40,7 +43,7 @@ under the License. <item name="Download" href="download.html"/> </menu> <menu name="Examples"> - <item name="Configuring Describe Goal" href="examples/describe-configuration.html"/> + <item name="Configure the describe goal" href="examples/describe-configuration.html"/> </menu> </body> </site>
