From d88c5f0973e35827dab13d3af2acba15b263435d Mon Sep 17 00:00:00 2001 From: Ozgun OZ Date: Mon, 3 Jun 2024 10:51:34 +0200 Subject: [PATCH] update documentation for exposed core extensions, fix anchors (#139) After having experimented with the custom modules as discussed in the issues https://github.com/eclipse-sisu/sisu.plexus/issues/35 and https://github.com/eclipse-sisu/sisu.plexus/issues/41, I would like to update the documentation. --- docs/plexus/index.html | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/plexus/index.html b/docs/plexus/index.html index acd6e635..b118bdfd 100644 --- a/docs/plexus/index.html +++ b/docs/plexus/index.html @@ -769,16 +769,44 @@

Custom Bindings

}
-

Maven Class Loading mechanism does not expose the Guice API to build plugins, but only to core extensions.

-

So you can only define custom bindings in core extensions.

-

Note that extensions does not have access to the API by default, you need to expose it yourself using the `extension.xml` config file. See the example [here](https://maven.apache.org/ref/3.9.0/maven-core/core-extensions.html) for more details.

+

Note that Maven Class Loading mechanism does not expose the Guice API to plugins by default, you need to expose it yourself using the `extension.xml` config file. This file is where we list the exposed APIs from maven core to plugins.

+

Since core extensions are the only way to modify any behaviour of maven core, we have to create a core extension and put this file in it in order to modify the exposed APIs.

-

Even if you define custom Guice modules in your build plugins by adding the classes in your Classpath, they will not be picked up by maven due to the separation of Classpaths.

-

If you want to read more about maven class loader, see documentation [here](https://maven.apache.org/guides/mini/guide-maven-classloading.html#Core_Classloader)

+

Even if you define custom Guice modules in your plugins by adding the Guice classes into your Classpath (by adding Guice libraries as dependencies in your pom.xml for example), they will not be picked up by maven due to the separation of Classpaths.

+

If you want to read more about maven class loader, see documentation here.

+

To activate the Guice API, put the following file extensions.xml in the /META-INF/maven/ folder of your core extension.

+ + 
+<extension>
+    <exportedPackages>
+        <exportedPackage>com.google.inject.*</exportedPackage>
+        <exportedPackage>com.google.inject.binder.*</exportedPackage>
+        <exportedPackage>com.google.inject.matcher.*</exportedPackage>
+        <exportedPackage>com.google.inject.name.*</exportedPackage>
+        <exportedPackage>com.google.inject.spi.*</exportedPackage>
+        <exportedPackage>com.google.inject.util.*</exportedPackage>
+        <exportedPackage>com.google.inject.internal.*</exportedPackage>
+    </exportedPackages>
+</extension>
+

Build your extensions as a jar, and put the its artifact identifiers in the .mvn/extensions.xml file to activate your extension, in the maven project where you want to use custom guice bindings.

+ 
<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.1.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.1.0
+                    https://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
+  <extension>
+    <groupId/>
+    <artifactId/>
+    <version/>
+  </extension>
+</extensions>
+ +

See the documentation here for more details on the exposed APIs by default.

+

Here is the documentation that explains how to define a core extension.

+