[
https://issues.apache.org/jira/browse/MTOOLCHAINS-49?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17822615#comment-17822615
]
ASF GitHub Bot commented on MTOOLCHAINS-49:
-------------------------------------------
gnodet commented on code in PR #14:
URL:
https://github.com/apache/maven-toolchains-plugin/pull/14#discussion_r1509154012
##########
src/site/apt/toolchains/discovery.apt.vm:
##########
@@ -0,0 +1,148 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+ ------
+ Discovery mechanism
+ ------
+ Guillaume Nodet
+ ------
+ 2024-02-28
+ ------
+
+JDK Toolchain discovery mechanism
+
+ Since version 3.2.0, the plugin provides a heuristic to discover installed
JDK toolchains, by looking
+ at known installation directories and at environment variables.
+
+ The list of discovered toolchains can be easily displayed using the command
+ <<<mvn
org.apache.maven.plugins:maven-toolchains-plugin:${project.version}:display-discovered-jdk-toolchains>>>.
+ This will print something like:
+
++---+
+[INFO] Discovered 10 JDK toolchains:
+[INFO] - /Users/gnodet/.sdkman/candidates/java/21.0.2-graalce
+[INFO] provides:
+[INFO] version: 21.0.2
+[INFO] runtime.name: OpenJDK Runtime Environment
+[INFO] runtime.version: 21.0.2+13-jvmci-23.1-b30
+[INFO] vendor: GraalVM Community
+[INFO] vendor.version: GraalVM CE 21.0.2+13.1
+[INFO] current: true
+[INFO] lts: true
+[INFO] env: JAVA_HOME,JAVA21_HOME
+...
++---+
+
+ If you have installed JDK using standard tools and they are not listed here,
feel free
+ to {{{../issue-management.html}raise an issue}}.
+
+ The discovery mechanism provides a few information for each discovered JDK:
+
+ * <<<version>>>: the JDK version
+
+ * <<<runtime.name>>>: the name of the JDK runtime
+
+ * <<<runtime.version>>>: the version of the JDK runtime
+
+ * <<<vendor>>>: the vendor name
+
+ * <<<vendor.version>>>: the vendor version
+
+ * <<<current>>>: set to <<<true>>> if this is the running JDK
+
+ * <<<lts>>>: set to <<<true>>> if JDK version is a long-term supported
version
+
+ * <<<env>>>: set to the comma separated list of <<<JAVA\{xyz\}_HOME>>>>
matching environment variables
+
+
+ The <<<select-jdk-toolchain>>> goal discovering and selecting a matching JDK.
+ The config below allows using the current JDK, or any other discovered JDK
>= 17.
+ The benefit is that the current JDK can be kept for speed, but ensuring the
usage of any JDK 17 or higher if
+ the current jdk is below the requirements.
+
++---+
+<properties>
+ <toolchain.jdk.version>[17,)</toolchain.jdk.version>
+<properties>
+
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-toolchains-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>select-jdk-toolchain</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
++---+
+
+ If you use environment variables to configure your JDKs, you can use the
following configuration to select
+ the toolchain which is configured using the <<<JAVA17_HOME>>> environment
variable.
+
++---+
+<properties>
+ <toolchain.jdk.version>JAVA17_HOME</toolchain.jdk.version>
+<properties>
++---+
+
+* Selection mechanism
+
+ Several properties can be used to express requirements to match against
discovered JDK toolchains:
+
+ * <<<version>>> / <<<toolchain.jdk.version>>>: a version range such as
<<<[17,18)>>> to match against the JDK version
+
+ * <<<runtimeName>>> / <<<toolchain.jdk.runtime.name>>>
+
+ * <<<runtimeVersion>>> / <<<toolchain.jdk.runtime.version>>>
+
+ * <<<vendor>>> / <<<toolchain.jdk.vendor>>>
+
+ * <<<env>>> / <<<toolchain.jdk.env>>>: the name of an environment variable
that the JDK toolchain must match
+
+ The <<<useJdk>>> can be used to define whether the current JDK can be used
if it matches the requirements.
+
+* Sorting
+
+ Multiple discovered JDK toolchains may match the above requirements. In
such a case, you may want to express
+ preferences to use to sort the toolchains. This can be done using the
<<<comparator>>> configuration which is a
+ comma separated list of criterions amongst the following:
+
+ * <<<lts>>>: prefer LTS toolchains
+
+ * <<<current>>>: prefer the current JDK
+
+ * <<<env>>>: prefer toolchains discovered from environment variables
+
+ * <<<version>>>: prefer higher JDK versions
+
+ * <<<vendor>>>: sort alphabetically by vendor name
+
+ The default value is <<<lts,current,env,version,vendor>>>.
+
+* Toolchains XML file
+
+ The generation of the <<<toolchains.xml>>> file is not necessary to use
discovered toolchains.
+ The <<<select-jdk-toolchain>>> will select a toolchain amongst explicitly
configured toolchains and discovered
+ toolchains. The information for discovered toolchains are cached in
<<<~/.m2/discovered-toolchains-cache.xml>>> file
Review Comment:
That's not completely right, as the discovery is two steps: find JDKs,
gather info for each JDK. Only the second step is cached. For in order to
simplify the doc, I'll go with your proposal.
> Automatic discovery of JDK toolchains
> -------------------------------------
>
> Key: MTOOLCHAINS-49
> URL: https://issues.apache.org/jira/browse/MTOOLCHAINS-49
> Project: Maven Toolchains Plugin
> Issue Type: Improvement
> Reporter: Guillaume Nodet
> Assignee: Guillaume Nodet
> Priority: Major
>
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
