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

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git


The following commit(s) were added to refs/heads/master by this push:
     new f969dc79 Merge the toolchains plugin pages into the toolchains guide
f969dc79 is described below

commit f969dc7932d66956aeacab965d1012843659d807
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 19:52:55 2026 +0000

    Merge the toolchains plugin pages into the toolchains guide
---
 content/filtered-resources/.htaccess               |   4 +
 .../markdown/guides/mini/guide-using-toolchains.md | 192 +++++++++++++++++++--
 2 files changed, 183 insertions(+), 13 deletions(-)

diff --git a/content/filtered-resources/.htaccess 
b/content/filtered-resources/.htaccess
index 4959d228..7e070003 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -30,9 +30,13 @@ Redirect Permanent /scm/scms-overview.html 
/pom-scm-urls.html#Supported_SCMs
 Redirect Permanent /plugins/maven-checkstyle-plugin/customize.html 
/plugins/maven-checkstyle-plugin/examples/custom-checker-config.html
 Redirect Permanent /plugins/maven-checkstyle-plugin/howto.html 
/plugins/maven-checkstyle-plugin/usage.html
 Redirect Permanent /plugins/maven-checkstyle-plugin/tips.html 
/plugins/maven-checkstyle-plugin/examples/multi-module-config.html
+Redirect Permanent 
/plugins/maven-compiler-plugin/examples/compile-using-different-jdk.html 
/guides/mini/guide-using-toolchains.html
 Redirect Permanent 
/plugins/maven-compiler-plugin/examples/set-compiler-release.html 
/guides/mini/guide-java-target.html
 Redirect Permanent 
/plugins/maven-compiler-plugin/examples/set-compiler-source-and-target.html 
/guides/mini/guide-java-target.html#Using_the_source_and_target_Options
 Redirect Permanent /plugins/maven-compiler-plugin/multirelease.html 
/guides/mini/guide-multi-release-jars.html
+Redirect Permanent /plugins/maven-toolchains-plugin/toolchains/index.html 
/guides/mini/guide-using-toolchains.html
+Redirect Permanent /plugins/maven-toolchains-plugin/toolchains/jdk.html 
/guides/mini/guide-using-toolchains.html#JDK_Toolchain
+Redirect Permanent /plugins/maven-toolchains-plugin/toolchains/custom.html 
/guides/mini/guide-using-toolchains.html#Custom_Toolchains
 
 Redirect Permanent /plugins/maven-artifact-plugin/reproducible.html 
/guides/mini/guide-reproducible-builds.html#Reading_the_artifact.3Acompare_output
 Redirect Permanent /shared/maven-archiver/examples/classpath.html 
/guides/mini/guide-manifest.html#Setting_Up_the_Classpath
diff --git a/content/markdown/guides/mini/guide-using-toolchains.md 
b/content/markdown/guides/mini/guide-using-toolchains.md
index 15021138..381b40a5 100644
--- a/content/markdown/guides/mini/guide-using-toolchains.md
+++ b/content/markdown/guides/mini/guide-using-toolchains.md
@@ -42,8 +42,7 @@ Below are some plugins which are toolchain-aware, with the 
toolchain-type used:
 |      jdk       | 
[`animal-sniffer-maven-plugin`](https://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/)
      | 1.3                 | MojoHaus      |
 |      jdk       | 
[`cassandra-maven-plugin`](https://www.mojohaus.org/cassandra-maven-plugin/)    
                           | 0.7.0-1             | MojoHaus      |
 |      jdk       | 
[`exec-maven-plugin`](https://www.mojohaus.org/exec-maven-plugin/)              
                           | 1.1.1               | MojoHaus      |
-|      jdk       | 
[`jdiff-maven-plugin`](https://www.mojohaus.org/jdiff-maven-plugin/)            
                           | 1.0-beta-1-SNAPSHOT | MojoHaus      |
-|      jdk       | 
[`keytool-maven-plugin`](https://www.mojohaus.org/keytool/keytool-maven-plugin/)
                           | 1.4                 | MojoHaus      |
+|      jdk       | [`keytool-maven-plugin`](https://www.mojohaus.org/keytool/) 
                                                | 1.4                 | 
MojoHaus      |
 |    protobuf    | 
[`protobuf-maven-plugin`](https://www.xolstice.org/protobuf-maven-plugin/examples/protobuf-toolchain.html)
 | 0.6.1               | github        |
 
 ## Using Toolchains in Your Project
@@ -63,12 +62,12 @@ For example, you want to use a different JDK version to 
build your project than
   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-compiler-plugin</artifactId>
-    <version>3.1</version>
+    <version>3.16.0</version>
   </plugin>
   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-toolchains-plugin</artifactId>
-    <version>1.1</version>
+    <version>3.3.0</version>
     <executions>
       <execution>
         <goals>
@@ -79,8 +78,8 @@ For example, you want to use a different JDK version to build 
your project than
     <configuration>
       <toolchains>
         <jdk>
-          <version>1.8</version>
-          <vendor>openjdk</vendor>
+          <version>21</version>
+          <vendor>temurin</vendor>
         </jdk>
       </toolchains>
     </configuration>
@@ -89,11 +88,11 @@ For example, you want to use a different JDK version to 
build your project than
 </plugins>
 ```
 
-As you can see in the example above, a JDK toolchain with `<version>` "1.8" 
and `<vendor>` "openjdk" is to be used. Now how does the plugin know where this 
JDK is installed? This is where the `toolchains.xml` file comes in.
+As you can see in the example above, a JDK toolchain with `<version>` "21" and 
`<vendor>` "temurin" is to be used. Now how does the plugin know where this JDK 
is installed? This is where the `toolchains.xml` file comes in.
 
-The `toolchains.xml` file (see below) is the configuration file where you set 
the installation paths of your toolchains. This file should be put in the 
`${user.home}/.m2` directory. When the `maven-toolchains-plugin` executes, it 
looks for the `toolchains.xml` file, reads it and looks for a toolchain 
matching the toolchains requirements configured in the plugin. In this example, 
that is a JDK toolchain with `<version>` "1.8" and `<vendor>` "openjdk". Once a 
match is found, the plugin the [...]
+The `toolchains.xml` file (see below) is the configuration file where you set 
the installation paths of your toolchains. This file should be put in the 
`${user.home}/.m2` directory. When the `maven-toolchains-plugin` executes, it 
looks for the `toolchains.xml` file, reads it and looks for a toolchain 
matching the toolchains requirements configured in the plugin. In this example, 
that is a JDK toolchain with `<version>` "21" and `<vendor>` "temurin". Once a 
match is found, the plugin then [...]
 
-Starting with [Maven 3.3.1](/docs/3.3.1/release-notes.html) you can put the 
`toolchains.xml` file wherever you like by using the `--global-toolchains file` 
option, but it is recommended to locate it into `${user.home}/.m2/`.
+Starting with [Maven 3.3.1](/docs/3.3.1/release-notes.html) you can put the 
`toolchains.xml` file wherever you like by using the `-t,--toolchains` option 
(or `-gt,--global-toolchains` for the global file), but it is recommended to 
locate it into `${user.home}/.m2/`.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -102,18 +101,18 @@ Starting with [Maven 
3.3.1](/docs/3.3.1/release-notes.html) you can put the `too
   <toolchain>
     <type>jdk</type>
     <provides>
-      <version>1.8</version>
-      <vendor>openjdk</vendor>
+      <version>21</version>
+      <vendor>temurin</vendor>
     </provides>
     <configuration>
-      <jdkHome>/path/to/jdk/1.8</jdkHome>
+      <jdkHome>/path/to/jdk/21</jdkHome>
     </configuration>
   </toolchain>
   <toolchain>
     <type>jdk</type>
     <provides>
       <version>17</version>
-      <vendor>azul</vendor>
+      <vendor>temurin</vendor>
     </provides>
     <configuration>
       <jdkHome>/path/to/jdk/17</jdkHome>
@@ -134,3 +133,170 @@ Starting with [Maven 
3.3.1](/docs/3.3.1/release-notes.html) you can put the `too
 ```
 
 You can configure as many toolchains as you want in your `toolchains.xml` file.
+
+Instead of writing the JDK entries by hand, the Toolchains Plugin can 
[discover the installed 
JDKs](/plugins/maven-toolchains-plugin/toolchains/jdk-discovery.html) and 
select a matching one with the 
[`toolchains:select-jdk-toolchain`](/plugins/maven-toolchains-plugin/select-jdk-toolchain-mojo.html)
 goal, or print them in `toolchains.xml` format with 
`toolchains:generate-jdk-toolchains-xml`.
+
+## JDK Toolchain
+
+The toolchain type id for JDK is `jdk`.
+
+Predefined `<provides>` identification tokens, for requirement matching in 
plugin configuration, are:
+
+- `version` marks the version of the JDK in `toolchains.xml`. In the plugin 
configuration, this can be either a single version or a [version 
range](/enforcer/enforcer-rules/versionRanges.html).
+- Other tokens, such as `vendor`, are accepted, but only exact matches are 
supported.
+
+In `toolchains.xml`, the only child of the `<configuration>` element is 
`jdkHome`. It designates the root directory of a JDK installation.
+
+The `toolchains.xml` above defines a toolchain with version 21 and vendor 
"temurin". A project can request it by specifying the type `jdk` and the 
version `21`. It can also use a version range that includes 21 like `[17, 25]`, 
or ask for the vendor `temurin`, with or without a version.
+
+Besides the `version`, the values are opaque strings. Maven looks in 
`toolchains.xml` for a toolchain that provides `version` "21" and `vendor` 
"temurin"; it does not know or care what these strings mean. It does not 
concern itself with whether the `jdkHome` of the matching toolchain is really 
JDK 21 from the Temurin project, or JDK 17 from another vendor. The JDK 
toolchain only checks that the directory exists. All conditions need to be 
satisfied to find a toolchain.
+
+For example, to accept any JDK of version 17 or greater:
+
+```xml
+<configuration>
+  <toolchains>
+    <jdk>
+      <version>[17,)</version>
+    </jdk>
+  </toolchains>
+</configuration>
+```
+
+## Setting a Toolchain for a Single Plugin
+
+The `maven-toolchains-plugin` configures one JDK toolchain for all the 
toolchain-aware plugins of the build. Since `maven-compiler-plugin` 3.6, used 
with Maven 3.3.1 or later, the compiler plugin also accepts its own toolchain 
with the 
[`jdkToolchain`](/plugins/maven-compiler-plugin/compile-mojo.html#jdkToolchain) 
parameter, which overrules the one selected by the `maven-toolchains-plugin`. 
This is useful when different executions need different JDKs, for example when 
the test sources ne [...]
+
+```xml
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-compiler-plugin</artifactId>
+  <version>3.16.0</version>
+  <configuration>
+    <jdkToolchain>
+      <version>17</version>
+    </jdkToolchain>
+  </configuration>
+</plugin>
+```
+
+## Compiling Without Toolchains
+
+Toolchains are the preferable way to use a different JDK. Outside of a 
toolchain, the Compiler Plugin can still be pointed at a specific `javac`. This 
configuration is specific to that plugin and does not affect the others. Set 
`fork` to `true` and give the path of the compiler in `executable`:
+
+```xml
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-compiler-plugin</artifactId>
+  <version>3.16.0</version>
+  <configuration>
+    <fork>true</fork>
+    <executable>${JAVA_17_HOME}/bin/javac</executable>
+  </configuration>
+</plugin>
+```
+
+To keep the build portable, each developer defines the property in 
[`settings.xml`](/ref/current/maven-settings/settings.html), or sets an 
environment variable:
+
+```xml
+<settings>
+  <profiles>
+    <profile>
+      <id>compiler</id>
+      <properties>
+        <JAVA_17_HOME>/path/to/jdk/17</JAVA_17_HOME>
+      </properties>
+    </profile>
+  </profiles>
+  <activeProfiles>
+    <activeProfile>compiler</activeProfile>
+  </activeProfiles>
+</settings>
+```
+
+To target an older Java version than the JDK that runs the compiler, see 
[Targeting a Java Version](/guides/mini/guide-java-target.html). If you build 
with a different JDK, you may also want to [customize the JAR 
manifest](/guides/mini/guide-manifest.html).
+
+## Custom Toolchains
+
+You can create custom toolchains to use with standard plugins (such as the 
`maven-compiler-plugin`) or with custom plugins.
+
+A full working sample is included in the `maven-toolchains-plugin` integration 
tests, which are part of [the plugin source 
tree](/plugins/maven-toolchains-plugin/scm.html):
+
+- `src/it/setup-custom-toolchain` holds the custom toolchain and plugin,
+- `src/it/use-custom-toolchain` holds a sample project using the toolchain 
through its plugin.
+
+### Creating a Custom Toolchain
+
+A toolchain consists of:
+
+- an interface extending 
[`org.apache.maven.toolchain.Toolchain`](/ref/current/maven-core/apidocs/org/apache/maven/toolchain/Toolchain.html),
+- an implementation of this interface. Extending 
[`org.apache.maven.toolchain.DefaultToolchain`](/ref/current/maven-core/apidocs/org/apache/maven/toolchain/DefaultToolchain.html)
 is strongly encouraged, since it provides 
[`org.apache.maven.toolchain.ToolchainPrivate`](/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainPrivate.html),
 which is an internal requirement,
+- a 
[`org.apache.maven.toolchain.ToolchainFactory`](/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainFactory.html),
 provided as [JSR-330 component](/maven-jsr330.html) annotated with 
`@Named("<toolchainType>")` (for example `@Named("custom")`) and `@Singleton`.
+
+### Creating a Plugin Using a Toolchain
+
+To find a tool, a plugin uses the 
[`ToolchainManager`](/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainManager.html)
 API to load the toolchain, then uses that toolchain object to find the tool's 
path:
+
+```java
+@Parameter(defaultValue = "${session}", readonly = true, required = true)
+private MavenSession session;
+
+private final ToolchainManager toolchainManager;
+
+@Inject
+public MyMojo(ToolchainManager toolchainManager) {
+    this.toolchainManager = toolchainManager;
+}
+
+public void execute() throws MojoExecutionException {
+    // get the custom toolchain
+    CustomToolchain toolchain = (CustomToolchain) 
toolchainManager.getToolchainFromBuildContext("custom", session);
+
+    if (toolchain == null) {
+        throw new MojoExecutionException(
+                "Could not find 'custom' toolchain: please check 
maven-toolchains-plugin configuration.");
+    }
+
+    getLog().info("Found 'custom' toolchain in build context.");
+
+    // get a tool from the toolchain
+    String path = toolchain.findTool("tool");
+
+    getLog().info("Found expected tool named 'tool' at following location: " + 
path);
+}
+```
+
+This code uses [Maven Plugin Tool 
Annotations](/plugin-tools/maven-plugin-plugin/examples/using-annotations.html).
+
+### Using the Custom Toolchain and its Plugin
+
+The custom toolchain implementation needs to be shared between the 
toolchain-aware plugin and `maven-toolchains-plugin`. This is done using a 
Maven extension:
+
+- if the toolchain is packaged with the plugin, declare the plugin as an 
extension:
+
+    ```xml
+    <plugin>
+      <groupId>...</groupId>
+      <artifactId>...</artifactId>
+      <version>...</version>
+      <extensions>true</extensions><!-- to share the custom toolchain with 
maven-toolchains-plugin -->
+    </plugin>
+    ```
+
+- if the toolchain is packaged separately, to be shared by multiple plugins, 
declare it as a build extension:
+
+    ```xml
+    <project>
+      <build>
+        <extensions>
+          <extension>
+            <groupId>...</groupId>
+            <artifactId>...</artifactId>
+            <version>...</version>
+          </extension>
+        </extensions>
+      </build>
+    </project>
+    ```
+
+Packaging a toolchain in its own artifact separate from the plugin is only 
useful when there are multiple plugins using the toolchain. If a custom 
toolchain will only be used by one plugin (possibly providing multiple goals), 
it is simpler to package the toolchain with the plugin in a single artifact.

Reply via email to