This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new 6ee2c5c442 [MNG-5987] document goals execution order
6ee2c5c442 is described below
commit 6ee2c5c442046dabf934f5fab1edc4cc7328424f
Author: Hervé Boutemy <[email protected]>
AuthorDate: Sun Jun 4 10:06:03 2023 +0200
[MNG-5987] document goals execution order
fixes #1145
---
maven-core/src/site/apt/index.apt | 19 ++++++++++++++++++-
maven-plugin-api/src/main/mdo/plugin.mdo | 7 ++++---
maven-plugin-api/src/site/apt/index.apt | 12 +++++++++---
maven-plugin-api/src/site/site.xml | 4 ++--
4 files changed, 33 insertions(+), 9 deletions(-)
diff --git a/maven-core/src/site/apt/index.apt
b/maven-core/src/site/apt/index.apt
index 47b884fdbb..7988dccc34 100644
--- a/maven-core/src/site/apt/index.apt
+++ b/maven-core/src/site/apt/index.apt
@@ -49,7 +49,24 @@ Maven Core
* <<<ProjectBuilder>>> component
({{{./apidocs/org/apache/maven/project/ProjectBuilder.html}javadoc}}),
with its <<<DefaultProjectBuilder>>> implementation
- ({{{./xref/org/apache/maven/project/DefaultProjectBuilder.html}source}}),
+ ({{{./xref/org/apache/maven/project/DefaultProjectBuilder.html}source}}), to
prepare
{{{./apidocs/org/apache/maven/project/MavenProject.html}<<<MavenProject>>>
descriptor}} from POM files,
+
+ * <<<LifecycleExecutor>>> component
({{{./apidocs/org/apache/maven/lifecycle/LifecycleExecutor.html}javadoc}}),
+ with its <<<DefaultLifecycleExecutor>>>
implementation({{{/xref/org/apache/maven/lifecycle/DefaultLifecycleExecutor.html}source}}),
to plan or execute tasks.\
+ on plugin goals execution order:
+
+ * <<in a given phase, goals order is not expected to be guaranteed nor
finely tuned>>:
+ it is just a consequence of the order obtained during
{{{../maven-model-builder/}effective model building}},
+ which combines profile activation+injection and inheritance assembly from
parents,
+
+ * known limitations are notably that:
+
+ 1. plugin goal execution in a child is usually simply appended (at end):
you can't try to insert in the middle of pre-existing inherited executions,
+
+ 2. append happens at plugin level first, then goal level, independently
from phases.
+ This means for example that adding pluginA:goal2 to pre-existing
(pluginA:goal1, pluginB:goal) will lead to (pluginA:goal1, pluginA:goal2,
pluginB:goal)
+
+ * see effective POM as shown by
{{{/plugins/maven-help-plugin/effective-pom-mojo.html}<<<help:effective-pom>>>}}
to see the effective plugins then goals order.
* <<<MavenPluginManager>>> component
({{{./apidocs/org/apache/maven/plugin/MavenPluginManager.html}javadoc}}),
with its <<<DefaultMavenPluginManager>>> implementation
diff --git a/maven-plugin-api/src/main/mdo/plugin.mdo
b/maven-plugin-api/src/main/mdo/plugin.mdo
index de4ea4b85f..ad1006df26 100644
--- a/maven-plugin-api/src/main/mdo/plugin.mdo
+++ b/maven-plugin-api/src/main/mdo/plugin.mdo
@@ -27,9 +27,10 @@ under the License.
Plugin descriptor, stored in <code>META-INF/maven/plugin.xml</code> in a
plugin's jar artifact.
This descriptor is generally generated from plugin sources, using
<a href="/plugins/maven-plugin-plugin/">maven-plugin-plugin</a>.
- <p><i>Notice:</i> this documentation is generated from a Modello model but
the code executed is not generated
- from this descriptor. Please report if you find anything wrong.</p>
- <p>An XSD is available at:<a
href="https://maven.apache.org/xsd/plugin-1.1.0.xsd";>https://maven.apache.org/xsd/plugin-1.1.0.xsd</a></p>
+ <p><i>Notice:</i> this documentation is generated from a Modello model but
the
+ <a
href="apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor.html"><code>PluginDescriptor</code></a>/<a
href="apidocs/org/apache/maven/plugin/descriptor/MojoDescriptor.html"><code>MojoDescriptor</code></a>
+ code executed is not generated from this model. Please report if you find
anything wrong this documentation.</p>
+ <p>An XSD is available at <a
href="https://maven.apache.org/xsd/plugin-1.1.0.xsd";>https://maven.apache.org/xsd/plugin-1.1.0.xsd</a></p>
]]></description>
<defaults>
<default>
diff --git a/maven-plugin-api/src/site/apt/index.apt
b/maven-plugin-api/src/site/apt/index.apt
index 6eb59556c6..e7a16aebe2 100644
--- a/maven-plugin-api/src/site/apt/index.apt
+++ b/maven-plugin-api/src/site/apt/index.apt
@@ -25,7 +25,13 @@
Maven Plugin API
- The API for plugins - composed of goals implemented by Mojos - development.
+ The API for plugins - composed of goals implemented by Mojos - development:
+
+ * goal code extends
{{{./apidocs/org/apache/maven/plugin/AbstractMojo.html}<<<AbstractMojo>>> base
class}} that implements
{{{./apidocs/org/apache/maven/plugin/Mojo.html}<<<Mojo>>> interface}},
+
+ * {{{./apidocs/org/apache/maven/plugin/logging/Log.html}<<<Log>>> interface}}
provides easy logging for the goal.
+
+ []
A plugin is described in a {{{./plugin.html}<<<META-INF/maven/plugin.xml>>>
plugin descriptor}},
generally generated from plugin sources using
{{{/plugin-tools/maven-plugin-plugin/}maven-plugin-plugin}}.
@@ -34,6 +40,6 @@ Maven Plugin API
* {{{/developers/mojo-api-specification.html}Mojo API Specification}}
- * {{{/plugin-tools/}plugin-tools}}
+ * {{{/plugin-tools/}Plugin Tools}} that provide
{{{/plugin-tools/maven-plugin-plugin/}maven-plugin-plugin}} to generate the
{{{./plugin.html}<<<META-INF/maven/plugin.xml>>> plugin descriptor}}
- * {{{/plugin-testing/}plugin-testing}}
+ * {{{/plugin-testing/}Plugin Testing}} frameworks
diff --git a/maven-plugin-api/src/site/site.xml
b/maven-plugin-api/src/site/site.xml
index 519623c9e7..1cbf42b096 100644
--- a/maven-plugin-api/src/site/site.xml
+++ b/maven-plugin-api/src/site/site.xml
@@ -32,8 +32,8 @@
<!--item name="FAQ" href="faq.html"/-->
</menu>
<menu name="Reference">
- <item name="lifecycle.xml" href="lifecycle-mappings.html"/>
- <item name="plugin.xml" href="plugin.html"/>
+ <item name="META-INF/maven/lifecycle.xml"
href="lifecycle-mappings.html"/>
+ <item name="META-INF/maven/plugin.xml" href="plugin.html"/>
</menu>
<menu ref="parent"/>
