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.