maven-help-plugin的插件使用总结

官网地址: http://maven.apache.org/plugins/maven-help-plugin/index.html

1. 功能描述

官网介绍:

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.

简单来说, 主要用来获取插件的详细使用信息. 其他功能见下面具体的goal

可脱离pom.xml目录单独执行

2. 所有goals

• help:active-profiles lists the profiles which are currently active for the build.
• help:all-profiles lists the available profiles under the current project.
• help:describe describes the attributes of a Plugin and/or a Mojo (Maven plain Old Java Object).
• help:effective-pom 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 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 evaluates Maven expressions given by the user in an interactive mode.
• help:system displays a list of the platform details like system properties and environment variables.

3. 常用场景

接触新的plugin时, 不知道怎么使用? (包含maven-help-plugin插件)
某个plugin的某个goal, 有哪些配置参数不清楚?
这时候, help插件就可以帮助我们学习这个plugin的详细使用方法:

1. 该plugin包含哪些goal?
2. 每个goal的作用是什么? 
3. 每个goal有哪些可选的配置参数?

• 使用plugin选项, 可以接受以下形式参数:

1.  plugin-prefix, i.e.  'mvn help:describe -Dplugin=help'
2.  groupId:artifactId, i.e. 'mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin'
3.  groupId:artifactId:version, i.e. 'mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.2.0'

• 如果仅需要查看某一个goal的用法, 加上goal选项

mvn help:describe -Dplugin=org.eclipse.jetty:jetty-maven-plugin:9.4.44.v20210927 -Dgoal=run-war

• 如果需要查看goal的详细介绍, 加上-Ddetail属性

mvn help:describe -Dplugin=help -Ddetail
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin -Ddetail
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.2.0 -Ddetail

运行结果如下, 和上述goal是一致的. 且包含了非常详细的使用说明:

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

This plugin has 8 goals:

help:active-profiles
  Description: Displays a list of the profiles which are currently active for
    this build.
  Implementation: org.apache.maven.plugins.help.ActiveProfilesMojo
  Language: java

  Available parameters:

    output
      User property: output
      Optional parameter to write the output of this help in a given file,
      instead of writing to the console.
      Note: Could be a relative path.

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.
  Implementation: org.apache.maven.plugins.help.AllProfilesMojo
  Language: java

  Available parameters:

    output
      User property: output
      Optional parameter to write the output of this help in a given file,
      instead of writing to the console.
      Note: Could be a relative path.

help:describe
  Description: Displays a list of the attributes for a Maven Plugin and/or
    goals (aka Mojo - Maven plain Old Java Object).
  Implementation: org.apache.maven.plugins.help.DescribeMojo
  Language: java

  Available parameters:

    artifactId
      User property: artifactId
      The Maven Plugin artifactId to describe.
      Note: Should be used with groupId parameter.

    cmd
      User property: cmd
      A Maven command like a single goal or a single phase following the Maven
      command line:
      mvn [options] [<goal(s)>] [<phase(s)>]

    detail (Default: false)
      User property: detail
      This flag specifies that a detailed (verbose) list of goal (Mojo)
      information should be given.

    goal
      User property: goal
      The goal name of a Mojo to describe within the specified Maven Plugin. If
      this parameter is specified, only the corresponding goal (Mojo) will be
      described, rather than the whole Plugin.

    groupId
      User property: groupId
      The Maven Plugin groupId to describe.
      Note: Should be used with artifactId parameter.

    minimal (Default: false)
      User property: minimal
      This flag specifies that a minimal list of goal (Mojo) information should
      be given.

    output
      User property: output
      Optional parameter to write the output of this help in a given file,
      instead of writing to the console.
      Note: Could be a relative path.

    plugin
      Alias: prefix
      User property: plugin
      The Maven Plugin to describe. This must be specified in one of three
      ways:
      
      1.  plugin-prefix, i.e. 'help'
      2.  groupId:artifactId, i.e. 'org.apache.maven.plugins:maven-help-plugin'
      3.  groupId:artifactId:version, i.e.
        'org.apache.maven.plugins:maven-help-plugin:2.0'

    version
      User property: version
      The Maven Plugin version to describe.
      Note: Should be used with groupId/artifactId parameters.

help:effective-pom
  Description: Displays the effective POM as an XML for this build, with the
    active profiles factored in, or a specified artifact. If verbose, a comment
    is added to each XML element describing the origin of the line.
  Implementation: org.apache.maven.plugins.help.EffectivePomMojo
  Language: java

  Available parameters:

    artifact
      User property: artifact
      The artifact for which to display the effective POM.
      Note: Should respect the Maven format, i.e. groupId:artifactId[:version].
      The latest version of the artifact will be used when no version is
      specified.

    output
      User property: output
      Optional parameter to write the output of this help in a given file,
      instead of writing to the console.
      Note: Could be a relative path.

    verbose (Default: false)
      User property: verbose
      Output POM input location as comments.

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.
  Implementation: org.apache.maven.plugins.help.EffectiveSettingsMojo
  Language: java

  Available parameters:

    output
      User property: output
      Optional parameter to write the output of this help in a given file,
      instead of writing to the console.
      Note: Could be a relative path.

    showPasswords (Default: false)
      User property: showPasswords
      For security reasons, all passwords are hidden by default. Set this to
      true to show all passwords.

help:evaluate
  Description: Evaluates Maven expressions given by the user in an
    interactive mode.
  Implementation: org.apache.maven.plugins.help.EvaluateMojo
  Language: java

  Available parameters:

    artifact
      User property: artifact
      An artifact for evaluating Maven expressions.
      Note: Should respect the Maven format, i.e. groupId:artifactId[:version].
      The latest version of the artifact will be used when no version is
      specified.

    expression
      User property: expression
      An expression to evaluate instead of prompting. Note that this must not
      include the surrounding ${...}.

    forceStdout (Default: false)
      User property: forceStdout
      This options gives the option to output information in cases where the
      output has been suppressed by using -q (quiet option) in Maven. This is
      useful if you like to use maven-help-plugin:evaluate in a script call
      (for example in bash) like this:
      RESULT=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
      echo $RESULT
      This will only printout the information which has been requested by
      expression to stdout.

    output
      User property: output
      Optional parameter to write the output of this help in a given file,
      instead of writing to the console. This parameter will be ignored if no
      expression is specified.
      Note: Could be a relative path.

help:help
  Description: Display help information on maven-help-plugin.
    Call mvn help:help -Ddetail=true -Dgoal=<goal-name> to display parameter
    details.
  Implementation: org.apache.maven.plugins.help.HelpMojo
  Language: java

  Available parameters:

    detail (Default: false)
      User property: detail
      If true, display all settable properties for each goal.

    goal
      User property: goal
      The name of the goal for which to show help. If unspecified, all goals
      will be displayed.

    indentSize (Default: 2)
      User property: indentSize
      The number of spaces per indentation level, should be positive.

    lineLength (Default: 80)
      User property: lineLength
      The maximum length of a display line, should be positive.

help:system
  Description: Displays a list of the platform details like system properties
    and environment variables.
  Implementation: org.apache.maven.plugins.help.SystemMojo
  Language: java

  Available parameters:

    output
      User property: output
      Optional parameter to write the output of this help in a given file,
      instead of writing to the console.
      Note: Could be a relative path.

参考:
[1]: http://maven.apache.org/plugins/maven-help-plugin/index.html