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. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
