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 <[email protected]> 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> + ++----+ + + [] +
