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 <elh...@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.
+
