Author: svn-site-role Date: Sat Oct 31 21:20:30 2026 New Revision: 1939843 Log: f969dc7 Merge the toolchains plugin pages into the toolchains guide
Modified: maven/website/content/.htaccess maven/website/content/guides/mini/guide-using-toolchains.html Modified: maven/website/content/.htaccess ============================================================================== --- maven/website/content/.htaccess Sat Oct 31 21:18:39 2026 (r1939842) +++ maven/website/content/.htaccess Sat Oct 31 21:20:30 2026 (r1939843) @@ -30,9 +30,13 @@ Redirect Permanent /scm/scms-overview.ht 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 Modified: maven/website/content/guides/mini/guide-using-toolchains.html ============================================================================== --- maven/website/content/guides/mini/guide-using-toolchains.html Sat Oct 31 21:18:39 2026 (r1939842) +++ maven/website/content/guides/mini/guide-using-toolchains.html Sat Oct 31 21:20:30 2026 (r1939843) @@ -241,15 +241,10 @@ <td>MojoHaus</td></tr> <tr class="a"> <td>jdk</td> -<td><a href="https://www.mojohaus.org/jdiff-maven-plugin/" class="externalLink"><code>jdiff-maven-plugin</code></a></td> -<td>1.0-beta-1-SNAPSHOT</td> -<td>MojoHaus</td></tr> -<tr class="b"> -<td>jdk</td> -<td><a href="https://www.mojohaus.org/keytool/keytool-maven-plugin/" class="externalLink"><code>keytool-maven-plugin</code></a></td> +<td><a href="https://www.mojohaus.org/keytool/" class="externalLink"><code>keytool-maven-plugin</code></a></td> <td>1.4</td> <td>MojoHaus</td></tr> -<tr class="a"> +<tr class="b"> <td>protobuf</td> <td><a href="https://www.xolstice.org/protobuf-maven-plugin/examples/protobuf-toolchain.html" class="externalLink"><code>protobuf-maven-plugin</code></a></td> <td>0.6.1</td> @@ -271,12 +266,12 @@ <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> @@ -287,8 +282,8 @@ <configuration> <toolchains> <jdk> - <version>1.8</version> - <vendor>openjdk</vendor> + <version>21</version> + <vendor>temurin</vendor> </jdk> </toolchains> </configuration> @@ -296,9 +291,9 @@ ... </plugins> </code></pre> -<p>As you can see in the example above, a JDK toolchain with <code><version></code> “1.8” and <code><vendor></code> “openjdk” is to be used. Now how does the plugin know where this JDK is installed? This is where the <code>toolchains.xml</code> file comes in.</p> -<p>The <code>toolchains.xml</code> file (see below) is the configuration file where you set the installation paths of your toolchains. This file should be put in the <code>${user.home}/.m2</code> directory. When the <code>maven-toolchains-plugin</code> executes, it looks for the <code>toolchains.xml</code> 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 <code><version></code> “1.8” and <code><vendor></code> “openjdk”. Once a match is found, the plugin then stores the toolchain to be used in the MavenSession. As you can see in the <code>toolchains.xml</code> below, there is indeed a JDK toolchain with <code><version></code> “1.8” and <code><vendor></code> “openjdk” configured. So when the <code>maven-compiler-plugin</code> configured in the <code>pom.xml</code> above executes, it sees that a JDK toolchain is set in the MavenSession and will use that toolchain (that would be the JDK installed at <code>/path/to/jdk/1.8</code> in this example) to compile the sources.</p> -<p>Starting with <a href="/docs/3.3.1/release-notes.html">Maven 3.3.1</a> you can put the <code>toolchains.xml</code> file wherever you like by using the <code>--global-toolchains file</code> option, but it is recommended to locate it into <code>${user.home}/.m2/</code>.</p> +<p>As you can see in the example above, a JDK toolchain with <code><version></code> “21” and <code><vendor></code> “temurin” is to be used. Now how does the plugin know where this JDK is installed? This is where the <code>toolchains.xml</code> file comes in.</p> +<p>The <code>toolchains.xml</code> file (see below) is the configuration file where you set the installation paths of your toolchains. This file should be put in the <code>${user.home}/.m2</code> directory. When the <code>maven-toolchains-plugin</code> executes, it looks for the <code>toolchains.xml</code> 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 <code><version></code> “21” and <code><vendor></code> “temurin”. Once a match is found, the plugin then stores the toolchain to be used in the MavenSession. As you can see in the <code>toolchains.xml</code> below, there is indeed a JDK toolchain with <code><version></code> “21” and <code><vendor></code> “temurin” configured. So when the <code>maven-compiler-plugin</code> configured in the <code>pom.xml</code> above executes, it sees that a JDK toolchain i s set in the MavenSession and will use that toolchain (that would be the JDK installed at <code>/path/to/jdk/21</code> in this example) to compile the sources.</p> +<p>Starting with <a href="/docs/3.3.1/release-notes.html">Maven 3.3.1</a> you can put the <code>toolchains.xml</code> file wherever you like by using the <code>-t,--toolchains</code> option (or <code>-gt,--global-toolchains</code> for the global file), but it is recommended to locate it into <code>${user.home}/.m2/</code>.</p> <pre class="prettyprint linenums"><code class="language-xml"><?xml version="1.0" encoding="UTF-8"?> <toolchains> @@ -306,18 +301,18 @@ <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> @@ -336,7 +331,151 @@ </toolchain> </toolchains> </code></pre> -<p>You can configure as many toolchains as you want in your <code>toolchains.xml</code> file.</p></section></section> </main> +<p>You can configure as many toolchains as you want in your <code>toolchains.xml</code> file.</p> +<p>Instead of writing the JDK entries by hand, the Toolchains Plugin can <a href="/plugins/maven-toolchains-plugin/toolchains/jdk-discovery.html">discover the installed JDKs</a> and select a matching one with the <a href="/plugins/maven-toolchains-plugin/select-jdk-toolchain-mojo.html"><code>toolchains:select-jdk-toolchain</code></a> goal, or print them in <code>toolchains.xml</code> format with <code>toolchains:generate-jdk-toolchains-xml</code>.</p></section><section><a id="JDK_Toolchain"></a> +<h2>JDK Toolchain</h2> +<p>The toolchain type id for JDK is <code>jdk</code>.</p> +<p>Predefined <code><provides></code> identification tokens, for requirement matching in plugin configuration, are:</p> +<ul> + +<li><code>version</code> marks the version of the JDK in <code>toolchains.xml</code>. In the plugin configuration, this can be either a single version or a <a href="/enforcer/enforcer-rules/versionRanges.html">version range</a>.</li> +<li>Other tokens, such as <code>vendor</code>, are accepted, but only exact matches are supported.</li> +</ul> +<p>In <code>toolchains.xml</code>, the only child of the <code><configuration></code> element is <code>jdkHome</code>. It designates the root directory of a JDK installation.</p> +<p>The <code>toolchains.xml</code> above defines a toolchain with version 21 and vendor “temurin”. A project can request it by specifying the type <code>jdk</code> and the version <code>21</code>. It can also use a version range that includes 21 like <code>[17, 25]</code>, or ask for the vendor <code>temurin</code>, with or without a version.</p> +<p>Besides the <code>version</code>, the values are opaque strings. Maven looks in <code>toolchains.xml</code> for a toolchain that provides <code>version</code> “21” and <code>vendor</code> “temurin”; it does not know or care what these strings mean. It does not concern itself with whether the <code>jdkHome</code> 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.</p> +<p>For example, to accept any JDK of version 17 or greater:</p> + +<pre class="prettyprint linenums"><code class="language-xml"><configuration> + <toolchains> + <jdk> + <version>[17,)</version> + </jdk> + </toolchains> +</configuration> +</code></pre></section><section><a id="Setting_a_Toolchain_for_a_Single_Plugin"></a> +<h2>Setting a Toolchain for a Single Plugin</h2> +<p>The <code>maven-toolchains-plugin</code> configures one JDK toolchain for all the toolchain-aware plugins of the build. Since <code>maven-compiler-plugin</code> 3.6, used with Maven 3.3.1 or later, the compiler plugin also accepts its own toolchain with the <a href="/plugins/maven-compiler-plugin/compile-mojo.html#jdkToolchain"><code>jdkToolchain</code></a> parameter, which overrules the one selected by the <code>maven-toolchains-plugin</code>. This is useful when different executions need different JDKs, for example when the test sources need a different compiler than the main sources:</p> + +<pre class="prettyprint linenums"><code class="language-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> +</code></pre></section><section><a id="Compiling_Without_Toolchains"></a> +<h2>Compiling Without Toolchains</h2> +<p>Toolchains are the preferable way to use a different JDK. Outside of a toolchain, the Compiler Plugin can still be pointed at a specific <code>javac</code>. This configuration is specific to that plugin and does not affect the others. Set <code>fork</code> to <code>true</code> and give the path of the compiler in <code>executable</code>:</p> + +<pre class="prettyprint linenums"><code class="language-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> +</code></pre> +<p>To keep the build portable, each developer defines the property in <a href="/ref/current/maven-settings/settings.html"><code>settings.xml</code></a>, or sets an environment variable:</p> + +<pre class="prettyprint linenums"><code class="language-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> +</code></pre> +<p>To target an older Java version than the JDK that runs the compiler, see <a href="/guides/mini/guide-java-target.html">Targeting a Java Version</a>. If you build with a different JDK, you may also want to <a href="/guides/mini/guide-manifest.html">customize the JAR manifest</a>.</p></section><section><a id="Custom_Toolchains"></a> +<h2>Custom Toolchains</h2> +<p>You can create custom toolchains to use with standard plugins (such as the <code>maven-compiler-plugin</code>) or with custom plugins.</p> +<p>A full working sample is included in the <code>maven-toolchains-plugin</code> integration tests, which are part of <a href="/plugins/maven-toolchains-plugin/scm.html">the plugin source tree</a>:</p> +<ul> + +<li><code>src/it/setup-custom-toolchain</code> holds the custom toolchain and plugin,</li> +<li><code>src/it/use-custom-toolchain</code> holds a sample project using the toolchain through its plugin.</li> +</ul><section><a id="Creating_a_Custom_Toolchain"></a> +<h3>Creating a Custom Toolchain</h3> +<p>A toolchain consists of:</p> +<ul> + +<li>an interface extending <a href="/ref/current/maven-core/apidocs/org/apache/maven/toolchain/Toolchain.html"><code>org.apache.maven.toolchain.Toolchain</code></a>,</li> +<li>an implementation of this interface. Extending <a href="/ref/current/maven-core/apidocs/org/apache/maven/toolchain/DefaultToolchain.html"><code>org.apache.maven.toolchain.DefaultToolchain</code></a> is strongly encouraged, since it provides <a href="/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainPrivate.html"><code>org.apache.maven.toolchain.ToolchainPrivate</code></a>, which is an internal requirement,</li> +<li>a <a href="/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainFactory.html"><code>org.apache.maven.toolchain.ToolchainFactory</code></a>, provided as <a href="/maven-jsr330.html">JSR-330 component</a> annotated with <code>@Named("<toolchainType>")</code> (for example <code>@Named("custom")</code>) and <code>@Singleton</code>.</li> +</ul></section><section><a id="Creating_a_Plugin_Using_a_Toolchain"></a> +<h3>Creating a Plugin Using a Toolchain</h3> +<p>To find a tool, a plugin uses the <a href="/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainManager.html"><code>ToolchainManager</code></a> API to load the toolchain, then uses that toolchain object to find the tool's path:</p> + +<pre class="prettyprint linenums"><code class="language-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); +} +</code></pre> +<p>This code uses <a href="/plugin-tools/maven-plugin-plugin/examples/using-annotations.html">Maven Plugin Tool Annotations</a>.</p></section><section><a id="Using_the_Custom_Toolchain_and_its_Plugin"></a> +<h3>Using the Custom Toolchain and its Plugin</h3> +<p>The custom toolchain implementation needs to be shared between the toolchain-aware plugin and <code>maven-toolchains-plugin</code>. This is done using a Maven extension:</p> +<ul> + +<li> +<p>if the toolchain is packaged with the plugin, declare the plugin as an extension:</p> + +<pre class="prettyprint linenums"><code class="language-xml"><plugin> + <groupId>...</groupId> + <artifactId>...</artifactId> + <version>...</version> + <extensions>true</extensions><!-- to share the custom toolchain with maven-toolchains-plugin --> +</plugin> +</code></pre></li> +<li> +<p>if the toolchain is packaged separately, to be shared by multiple plugins, declare it as a build extension:</p> + +<pre class="prettyprint linenums"><code class="language-xml"><project> + <build> + <extensions> + <extension> + <groupId>...</groupId> + <artifactId>...</artifactId> + <version>...</version> + </extension> + </extensions> + </build> +</project> +</code></pre></li> +</ul> +<p>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.</p></section></section></section> </main> </div> </div> <hr/>
