This is an automated email from the ASF dual-hosted git repository.
mbuenger pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new 35dac078 Update articles about plugin execution configuration
35dac078 is described below
commit 35dac078c01b563c563f45a5ed385d2ccc4e9ab0
Author: Matthias Bünger <buk...@users.noreply.github.com>
AuthorDate: Tue Mar 18 16:20:21 2025 +0100
Update articles about plugin execution configuration
This PR updates the articles about plugin configuration and lifecycle to
* make clear that Maven 4 breaks build when plugin is defined multiple
times [MNGSITE-519]
* describe execution merge and inheritance more clear [MNGSITE-362]
* add Maven 4 execution priorities
* fix some formatting errors in the affected pages
The additions are all in this PR as they affect the same section of the
configuration page.
Merge and inheritance behavior were verified with Maven 4.0.0-rc3 while
updating the docs.
---
.../introduction/introduction-to-the-lifecycle.apt | 11 +++--
.../apt/guides/mini/guide-configuring-plugins.apt | 49 ++++++++++++++++++----
content/apt/pom.apt.vm | 3 ++
3 files changed, 52 insertions(+), 11 deletions(-)
diff --git a/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
b/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
index 04dd686e..333b7840 100644
--- a/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
+++ b/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
@@ -126,8 +126,12 @@ mvn clean dependency:copy-dependencies package
Furthermore, a build phase can also have zero or more goals bound to it. If
a build phase has no goals bound to it,
that build phase will not execute. But if it has one or more goals bound to
it, it will execute all those goals.
~~~
- Multiple goals bound to a phase are executed in the same order as they are
declared in the
- POM. Multiple instances of the same plugin are grouped to execute together.
+ Multiple goals bound to a phase are executed in the same order as they are
declared in the POM.
+
+ It's possible to declare multiple executions for the same plugin - see
{{{./guides/mini/guide-configuring-plugins.html#Configuring_Build_Plugins}Configuring
plugins}} for more details.
+ <<Note>>: This does <<not>> mean that it's allowed to declare the same
plugin multiple times in {{{/pom.html#Plugins} <<<<plugins\>>>> declaration
section}}!
+ Declaring a plugin multiple times shows warnings using Maven 3 and fail the
build using Maven 4.
+
~~~
<{{{./introduction-to-the-lifecycle.html}[top]}}.>
@@ -242,8 +246,7 @@ mvn clean dependency:copy-dependencies package
with different configuration if needed. Separate executions can also be
given an ID so that during inheritance or the
application of profiles you can control whether goal configuration is merged
or turned into an additional execution.
- When multiple executions are given that match a particular phase, they are
executed in the order specified in the POM,
- with inherited executions running first.
+ See
{{{./guides/mini/guide-configuring-plugins.html#Configuring_Build_Plugins}Configuring
plugins}} for more details about the configuration of multiple executions and
their execution order.
Now, in the case of <<<modello:java>>>, it only makes sense in the
<<<generate-sources>>> phase. But some goals can be
used in more than one phase, and there may not be a sensible default. For
those, you can specify the phase yourself.
diff --git a/content/apt/guides/mini/guide-configuring-plugins.apt
b/content/apt/guides/mini/guide-configuring-plugins.apt
index 82247ae4..081ea49c 100644
--- a/content/apt/guides/mini/guide-configuring-plugins.apt
+++ b/content/apt/guides/mini/guide-configuring-plugins.apt
@@ -54,7 +54,7 @@ Guide to Configuring Plug-ins
<<Important Note>>: Always define the version of each plugin to guarantee
build reproducibility. A good practice is to specify each build plugin's
version in a <<<\<build\>\<pluginManagement/\>\</build\>>>>
- element. Often the \<pluginManagement/\> element is found in the parent POM.
+ element. Often the <<<<pluginManagement/\>>>> element is found in the parent
POM.
For reporting plugins, specify each version in the
<<<\<reporting\>\<plugins/\>\</reporting\>>>> element
(and in the <<<\<build\>\<pluginManagement/\>\</build\>>>> element too).
@@ -490,13 +490,16 @@ public class MyAnimalMojo
</project>
+----+
- The first execution with id "execution1" binds this configuration to the
test phase. The second execution does not
+ The first execution with id <<<execution1>>> binds this configuration to the
test phase. The second execution does not
have a <<<\<phase\>>>> tag, how do you think will this execution behave?
Well, goals can have a default phase binding
as discussed further below. If the goal has a default phase binding then it
will execute in that phase. But if the
goal is not bound to any lifecycle phase then it simply won't be executed
during the build lifecycle.
Note that while execution id's have to be unique among all executions of a
single plugin within a POM, they don't
- have to be unique across an inheritance hierarchy of POMs. Executions of
the same id from different POMs are merged.
+ have to be unique across an inheritance hierarchy of POMs.
+ Executions with different id's are merged, meaning they are all executed in
the hierarchy order (parent first).
+ Executions with the same id from different POMs are overwritten by child
configuration.
+
The same applies to executions that are defined by profiles.
How about if we have a multiple executions with different phases bound to it?
@@ -542,9 +545,41 @@ public class MyAnimalMojo
If there are multiple executions bound to different phases, then the mojo is
executed once for each phase indicated. Meaning, <<<execution1>>> will be
- executed applying the configuration setup when the phase of the build is
test,
- and <<<execution2>>> will be executed applying the configuration setup when
- the build phase is already in install.
+ executed applying the configuration setup during the test phase,
+ while <<<execution2>>> will be executed applying the configuration setup
during the install phase.
+
+ It's possible to bind multiple executions to the same phase, for example if
you want to do multiple things inside the same phase.
+ Those are executed in the same order as they are declared in the POM.
+ This also applies to inherited definitions. A parents declaration is
execution before the child's declaration.
+ Since Maven 4 it's possible to explicit define the order of multiple
executions by using square brackets with an integer at the end of the phase
name.
+ A higher number means a later execution.
+ Using the following definition would execute <<<execution2>>> before
<<<execution1>>>, but both in the test phase.
+
++----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ ...
+ <executions>
+ <execution>
+ <id>execution1</id>
+ <phase>test[200]</phase>
+ ...
+ </execution>
+ <execution>
+ <id>execution2</id>
+ <phase>test[100]</phase>
+ ...
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++----+
Now, let us have another mojo example which shows a default lifecycle phase
binding.
@@ -619,7 +654,7 @@ public class MyBoundQueryMojo
of the plugin.
Since Maven 3.3.1 this is not the case anymore as you can specify on the
command line
the execution id for direct plugin goal invocation. Hence if you want to
- run the above plugin and it's specific execution1's configuration from the
+ run the above plugin and it's specific <<<execution1>>>'s configuration from
the
command-line, you can execute:
------
diff --git a/content/apt/pom.apt.vm b/content/apt/pom.apt.vm
index ad17db4a..7518220e 100644
--- a/content/apt/pom.apt.vm
+++ b/content/apt/pom.apt.vm
@@ -1006,6 +1006,9 @@ Display parameters as parsed by Maven (in canonical form
and as a list of tokens
Unlike dependencies, there is a default <<<groupId>>> for plugins.
See {{{/guides/mini/guide-configuring-plugins.html}Configuring Plugins}}.
+ <<Note>>: It is not allowed to declare the same plugin multiple times in the
same build.
+ Multiple declarations of the same plugin result in warnings using Maven 3
and fail the build using Maven 4.
+
Beyond the standard coordinate of <<<groupId:artifactId:version>>>, there
are elements which
configure the plugin or this builds interaction with it.
