You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2022/10/10 10:12:34 UTC

[maven-site] branch feature/improve-extensions-documentation created (now f7643d29)

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a change to branch feature/improve-extensions-documentation
in repository https://gitbox.apache.org/repos/asf/maven-site.git


      at f7643d29 [MNGSITE-496] Outline all means to load extensions and clarify differences

This branch includes the following new commits:

     new f7643d29 [MNGSITE-496] Outline all means to load extensions and clarify differences

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



[maven-site] 01/01: [MNGSITE-496] Outline all means to load extensions and clarify differences

Posted by kw...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch feature/improve-extensions-documentation
in repository https://gitbox.apache.org/repos/asf/maven-site.git

commit f7643d29dc1e46f23ec069413f7b7bf125010e7e
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Oct 10 12:12:26 2022 +0200

    [MNGSITE-496] Outline all means to load extensions and clarify
    differences
---
 .../examples/maven-3-lifecycle-extensions.apt.vm   | 67 ++++++++--------------
 content/apt/guides/mini/guide-using-extensions.apt | 66 +++++++++++++++------
 2 files changed, 70 insertions(+), 63 deletions(-)

diff --git a/content/apt/examples/maven-3-lifecycle-extensions.apt.vm b/content/apt/examples/maven-3-lifecycle-extensions.apt.vm
index d71084cf..0aac0079 100644
--- a/content/apt/examples/maven-3-lifecycle-extensions.apt.vm
+++ b/content/apt/examples/maven-3-lifecycle-extensions.apt.vm
@@ -28,7 +28,7 @@
 
 Example: Using Maven 3 lifecycle extension
 
-* Lifecyle Participation
+* Lifecycle Extension Points
 
   You can extend multiple classes depending on your needs:
 
@@ -36,11 +36,11 @@ Example: Using Maven 3 lifecycle extension
 
   * {{{/ref/current/maven-core/apidocs/index.html?org/apache/maven/AbstractMavenLifecycleParticipant.html}<<<org.apache.maven.AbstractMavenLifecycleParticipant>>>}},
 
-  * {{{/ref/current/maven-core/apidocs/index.html?org/apache/maven/eventspy/AbstractEventSpy.html}<<<org.apache.maven.eventspy.AbstractEventSpy>>>}},
+  * {{{/ref/current/maven-core/apidocs/index.html?org/apache/maven/eventspy/AbstractEventSpy.html}<<<org.apache.maven.eventspy.AbstractEventSpy>>>}}
 
   []
 
-* Build your extension
+* Build Your Extension
 
   Create a Maven project with a dependency on <<<org.apache.maven:maven-core:${currentStableVersion}>>> and other dependencies:
 
@@ -53,21 +53,23 @@ Example: Using Maven 3 lifecycle extension
       <groupId>org.apache.maven</groupId>
       <artifactId>maven-core</artifactId>
       <version>${currentStableVersion}</version>
+      <scope>provided</scope> <!-- always provided by the Maven Core Classloader -->
     </dependency>
 
-    <!-- dependency for plexus annotation -->
+    <!-- dependency for JSR 330 annotation -->
     <dependency>
-      <groupId>org.codehaus.plexus</groupId>
-      <artifactId>plexus-component-annotations</artifactId>
-      <version>1.7.1</version>
+      <groupId>javax.inject</groupId>
+      <artifactId>javax.inject</artifactId>
+      <version>1</version> 
+      <scope>provided</scope> <!-- always provided by the Maven Core Classloader -->
     </dependency>
 +---+
 
-  Create your extension class
+  Create your extension class; your extension must be a {{{https://www.eclipse.org/sisu/}Sisu component}}, therefore mark it with the JSR 330 (or legacy Plexus container) annotation:
 
 +---+
-// your extension must be a "Plexus" component so mark it with the annotation
-@Component( role = AbstractMavenLifecycleParticipant.class, hint = "beer")
+@Named( "beer")
+@Singleton
 public class BeerMavenLifecycleParticipant extends AbstractMavenLifecycleParticipant
 {
 
@@ -89,7 +91,7 @@ public class BeerMavenLifecycleParticipant extends AbstractMavenLifecyclePartici
 }
 +---+
 
-  Generate plexus metadata during the build of your extension jar:
+  Generate {{{https://eclipse.github.io/sisu.mojos/}Sisu index files}} during the build of your extension jar:
 
 +---+
   <build>
@@ -97,13 +99,14 @@ public class BeerMavenLifecycleParticipant extends AbstractMavenLifecyclePartici
     <plugins>
       ...
       <plugin>
-        <groupId>org.codehaus.plexus</groupId>
-        <artifactId>plexus-component-metadata</artifactId>
-        <version>1.7.1</version>
+        <groupId>org.eclipse.sisu</groupId>
+        <artifactId>sisu-maven-plugin</artifactId>
+        <version>0.3.5</version>
         <executions>
           <execution>
+            <id>generate-index</id>
             <goals>
-              <goal>generate-metadata</goal>
+              <goal>main-index</goal>
             </goals>
           </execution>
         </executions>
@@ -114,35 +117,11 @@ public class BeerMavenLifecycleParticipant extends AbstractMavenLifecyclePartici
   </build>
 +---+
 
-* Use your extension in your build(s)
+* Load Your Extension
 
-  You have 3 ways to use your extension within your builds:
+ Use your extension in your build(s) via one of the means outlined at {{{../guides/mini/guide-using-extensions.html}Guide to using Extensions}}
 
-  * add your extension jar in <<<$\{maven.home\}/lib/ext>>>,
+  Whether late registration is sufficient or early registration is required depends on the implemented interface/extended class,
+  e.g. <<<AbstractMavenLifecycleParticipant.afterSessionStart()>>> is not called for components registered late.
 
-  * add it as a build extension in your pom,
-
-  * (since Maven 3.3.1) configure your extension in {{{/ref/current/maven-embedder/core-extensions.html}<<<.mvn/extensions.xml>>>}}.
-
-  []
-
-  <<NOTE>>: if you use the build extension mechanism, the method <<<afterSessionStart>>> <<won't be called>> since the extension
-  is loaded later in the build
-
-  To use a build extension in your project, declare it in your pom as:
-
-+---+
-   <build>
-     ...
-     <extensions>
-       ...
-       <extension>
-         <groupId>org.apache.maven.extensions</groupId>
-         <artifactId>beer-maven-lifecycle</artifactId>
-         <version>1.0-SNAPSHOT</version>
-       </extension>
-       ...
-     </extensions>
-    ...
-   </build>
-+---+
+  []
\ No newline at end of file
diff --git a/content/apt/guides/mini/guide-using-extensions.apt b/content/apt/guides/mini/guide-using-extensions.apt
index 02614d57..115fe5bc 100644
--- a/content/apt/guides/mini/guide-using-extensions.apt
+++ b/content/apt/guides/mini/guide-using-extensions.apt
@@ -28,34 +28,37 @@
 
 Using Extensions
 
- Extensions are a way to add libraries to {{{./guide-maven-classloading.html#Core_Classloader}Core Classloader}}.
+ Extensions are a way to add classes to {{{./guide-maven-classloading.html#Core_Classloader}Core Classloader}}.
+ This is necessary for adjusting Maven in a way that affects more than just one plug-in.
 
+ The mechanism allows to either replace default {{{https://www.eclipse.org/sisu/}Sisu components}} with custom ones or add
+ new components which are used at run time. In addition one could also expose additional packages from the Core Classloader.
+ 
  Extensions are typically used to enable 
  {{{../../wagon/wagon-providers/}Wagon providers}}, used for the transport 
- of artifact between repositories, and plug-ins which provide lifecycle enhancements.
+ of artifact between repositories, and plug-ins which {{{../../examples/maven-3-lifecycle-extensions.html}provide lifecycle enhancements}}.
 
-* Wagon providers
+* Loading Extensions
 
-+----+
+ There are different means of loading extensions. They can be distinguished into <<early>> and <<late>> loading behaviour. Some extensions require early loading.
+ Please refer to the extension's documentation whether early loading is required.
 
-<project>
-  ...
-  <build>
-    <extensions>
-      <extension>
-        <groupId>org.apache.maven.wagon</groupId>
-         <artifactId>wagon-ftp</artifactId>
-         <version>2.10</version>
-      </extension>
-    </extensions>
-  </build>
-  ...
-</project>
+** Early Loading
 
-+----+
+  * Registered via extension jar in <<<$\{maven.home\}/lib/ext>>>
 
-* Plug-ins which provide lifecycle enhancements
+  * Registered via CLI argument <<<mvn -Dmaven.ext.class.path=extension.jar>>>
 
+  * Registered via {{{../../configure.html#mvn-extensions-xml-file}<<<.mvn/extensions.xml>>> file}}
+
+  []
+
+** Late Loading
+
+  * Registered via {{{../../pom.html#Plugins}<<<project->build->plugins->plugin>>>}} with element <<<extensions>>> being set to <<<true>>>. This is useful for regular plug-ins carrying some extensions.
+  
+  Example:
+  
 +----+
 
 <project>
@@ -76,3 +79,28 @@ Using Extensions
 </project>
 
 +----+
+  
+  * Registered as build extension in {{{../../pom.html##Extensions}<<<project->build->extensions->extension>>>}}
+
+  Example:
+
++----+
+
+<project>
+  ...
+  <build>
+    <extensions>
+      <extension>
+        <groupId>org.apache.maven.wagon</groupId>
+         <artifactId>wagon-ftp</artifactId>
+         <version>2.10</version>
+      </extension>
+    </extensions>
+  </build>
+  ...
+</project>
+
++----+
+  
+  []
+