(maven-toolchains-plugin) 01/01: RewriteJDK toolchain docs

[el...@apache.org]

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

elharo pushed a commit to branch elharo-patch-1
in repository https://gitbox.apache.org/repos/asf/maven-toolchains-plugin.git

commit 9d0a65a4b5e047a74dcf1a0da848bc1c785b8292
Author: Elliotte Rusty Harold <el...@users.noreply.github.com>
AuthorDate: Sun Feb 25 14:40:23 2024 +0000

    RewriteJDK toolchain docs
    
    @slawekjaranowski
---
 src/site/apt/toolchains/jdk.apt.vm | 57 +++++++++++++++++++++++++-------------
 1 file changed, 38 insertions(+), 19 deletions(-)

diff --git a/src/site/apt/toolchains/jdk.apt.vm b/src/site/apt/toolchains/jdk.apt.vm
index 8e85e1e..52ce598 100644
--- a/src/site/apt/toolchains/jdk.apt.vm
+++ b/src/site/apt/toolchains/jdk.apt.vm
@@ -32,16 +32,16 @@ JDK Toolchain
  
   Predefined identification tokens, for requirement matching, are:
 
-  * "<<<version>>>" marks the version of the jdk. Maven Toolchains Plugin can match against a single version or any version ranges,
+  * "<<<version>>>" marks the version of the JDK. This can be either a single version or a version range.
 
-  * any other tokens will be accepted, but only exact matches are supported.
+  * Other are accepted, but only exact matches are supported.
 
   []
 
 * Toolchain Configuration
 
   There is only one configuration element named "<<<jdkHome>>>". It designates the root directory
-  of JDK installation.
+  of a JDK installation.
 
 * Sample <<<toolchains.xml>>> setup
 
@@ -50,33 +50,27 @@ JDK Toolchain
   <toolchain>
     <type>jdk</type>
     <provides>
-      <version>1.5</version>
-      <vendor>sun</vendor>
-      <id>for_mevenide</id>
+      <version>11</version>
+      <vendor>temurin</vendor>
+      <purpose>for_mevenide</purpose>
     </provides>
     <configuration>
-      <jdkHome>/home/mkleint/javatools/jdk</jdkHome>
+      <jdkHome>/Library/Java/JavaVirtualMachines/temurin-11.jdk/Contents/Home</jdkHome>
     </configuration>
   </toolchain>
   [...]
 </toolchains>
 +---+
 
-* Toolchains Plugin Configuration
-
-  For selection of toolchain for use by the project, the following conditions are matched
-  against the definitions in the <<<toolchains.xml>>> file:
-
-  * "<<<version>>>" which accepts any {{{/enforcer/enforcer-rules/versionRanges.html}version range definitions}}.
-    Version declared by the toolchain needs to fit into the range,
+This defines a toolchain with version 11, vendor "temurin", and purpose "for_mevenide". A project can request toolchain
+by specifying the type "jdk" and the version "11". It can also use a version range that includes 11 like [8, 17].
+It can also ask for the vendor temurin, with or without version, or the purpose "for_mevenide". 
 
-  * any other tokens needs exact match. Toolchain not providing such token will not be selected.
 
-  []
+* Toolchains Plugin Configuration
 
-  All conditions need to be satisfied in a sucessfully matched toolchain.
 
-* Sample Plugin Configuration
+A project specifies a toolchain in the conmfiguraiton of the maven-toolchains-plugin like so: 
 
 +---+
 <project>
@@ -97,7 +91,7 @@ JDK Toolchain
         <configuration>
           <toolchains>
             <jdk>
-              <version>[1.5,)</version>
+              <version>[1.8,)</version>
             </jdk>
           </toolchains>
         </configuration>
@@ -107,3 +101,28 @@ JDK Toolchain
   [...]
 </project>
 +---+
+
+In this example, the project is requesting any toolchain with type jdk that has a version of 1.8 or greater. 
+ "<<<version>>>" accepts any {{{/enforcer/enforcer-rules/versionRanges.html}version range definitions}}.
+If you want exactly JDK 1.8 from the vendor temurin, the plugin would be configured like this:
+
++---+
+        <configuration>
+          <toolchains>
+            <jdk>
+              <version>1.8</version>
+              <vendor>temurin</vendor>
+            </jdk>
+          </toolchains>
+        </configuration>
++---+
+
+Aside from version, the definitions are opaque strings. Maven looks in toolchains.xml
+for a toolchain that provides version=="1.8" and vendor=="temurin". It does not know or care
+what these strings mean. It does not, for instance, concern itself with whether the jdkHome configured 
+by the toolchain that satisfies version=="1.8" and vendor=="temurin" is JDK 8 from the Temurin project,
+or JDK 21 from Oracle. It might not even exist.
+
+
+All conditions need to be satisfied to find a toolchain.
+