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 @@
   &lt;plugin&gt;
     &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
     &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
-    &lt;version&gt;3.1&lt;/version&gt;
+    &lt;version&gt;3.16.0&lt;/version&gt;
   &lt;/plugin&gt;
   &lt;plugin&gt;
     &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
     &lt;artifactId&gt;maven-toolchains-plugin&lt;/artifactId&gt;
-    &lt;version&gt;1.1&lt;/version&gt;
+    &lt;version&gt;3.3.0&lt;/version&gt;
     &lt;executions&gt;
       &lt;execution&gt;
         &lt;goals&gt;
@@ -287,8 +282,8 @@
     &lt;configuration&gt;
       &lt;toolchains&gt;
         &lt;jdk&gt;
-          &lt;version&gt;1.8&lt;/version&gt;
-          &lt;vendor&gt;openjdk&lt;/vendor&gt;
+          &lt;version&gt;21&lt;/version&gt;
+          &lt;vendor&gt;temurin&lt;/vendor&gt;
         &lt;/jdk&gt;
       &lt;/toolchains&gt;
     &lt;/configuration&gt;
@@ -296,9 +291,9 @@
   ...
 &lt;/plugins&gt;
 </code></pre>
-<p>As you can see in the example above, a JDK toolchain with 
<code>&lt;version&gt;</code> &#x201c;1.8&#x201d; and 
<code>&lt;vendor&gt;</code> &#x201c;openjdk&#x201d; 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>&lt;version&gt;</code> &#x201c;1.8&#x201d; and 
<code>&lt;vendor&gt;</code> &#x201c;openjdk&#x201d;. 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>&lt;version&gt;</code> &#x201c;1.8&#x201d; and 
<code>&lt;vendor&gt;</code> &#x201c;openjdk&#x201d; 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>&lt;version&gt;</code> &#x201c;21&#x201d; and <code>&lt;vendor&gt;</code> 
&#x201c;temurin&#x201d; 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>&lt;version&gt;</code> &#x201c;21&#x201d; and 
<code>&lt;vendor&gt;</code> &#x201c;temurin&#x201d;. 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>&lt;version&gt;</code> &#x201c;21&#x201d; and <code>&lt;vendor&gt;</code> 
&#x201c;temurin&#x201d; 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">&lt;?xml 
version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
 &lt;toolchains&gt;
@@ -306,18 +301,18 @@
   &lt;toolchain&gt;
     &lt;type&gt;jdk&lt;/type&gt;
     &lt;provides&gt;
-      &lt;version&gt;1.8&lt;/version&gt;
-      &lt;vendor&gt;openjdk&lt;/vendor&gt;
+      &lt;version&gt;21&lt;/version&gt;
+      &lt;vendor&gt;temurin&lt;/vendor&gt;
     &lt;/provides&gt;
     &lt;configuration&gt;
-      &lt;jdkHome&gt;/path/to/jdk/1.8&lt;/jdkHome&gt;
+      &lt;jdkHome&gt;/path/to/jdk/21&lt;/jdkHome&gt;
     &lt;/configuration&gt;
   &lt;/toolchain&gt;
   &lt;toolchain&gt;
     &lt;type&gt;jdk&lt;/type&gt;
     &lt;provides&gt;
       &lt;version&gt;17&lt;/version&gt;
-      &lt;vendor&gt;azul&lt;/vendor&gt;
+      &lt;vendor&gt;temurin&lt;/vendor&gt;
     &lt;/provides&gt;
     &lt;configuration&gt;
       &lt;jdkHome&gt;/path/to/jdk/17&lt;/jdkHome&gt;
@@ -336,7 +331,151 @@
   &lt;/toolchain&gt;
 &lt;/toolchains&gt;
 </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>&lt;provides&gt;</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>&lt;configuration&gt;</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 &#x201c;temurin&#x201d;. 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> &#x201c;21&#x201d; and <code>vendor</code> 
&#x201c;temurin&#x201d;; 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">&lt;configuration&gt;
+  &lt;toolchains&gt;
+    &lt;jdk&gt;
+      &lt;version&gt;[17,)&lt;/version&gt;
+    &lt;/jdk&gt;
+  &lt;/toolchains&gt;
+&lt;/configuration&gt;
+</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">&lt;plugin&gt;
+  &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+  &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
+  &lt;version&gt;3.16.0&lt;/version&gt;
+  &lt;configuration&gt;
+    &lt;jdkToolchain&gt;
+      &lt;version&gt;17&lt;/version&gt;
+    &lt;/jdkToolchain&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;
+</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">&lt;plugin&gt;
+  &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+  &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
+  &lt;version&gt;3.16.0&lt;/version&gt;
+  &lt;configuration&gt;
+    &lt;fork&gt;true&lt;/fork&gt;
+    &lt;executable&gt;${JAVA_17_HOME}/bin/javac&lt;/executable&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;
+</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">&lt;settings&gt;
+  &lt;profiles&gt;
+    &lt;profile&gt;
+      &lt;id&gt;compiler&lt;/id&gt;
+      &lt;properties&gt;
+        &lt;JAVA_17_HOME&gt;/path/to/jdk/17&lt;/JAVA_17_HOME&gt;
+      &lt;/properties&gt;
+    &lt;/profile&gt;
+  &lt;/profiles&gt;
+  &lt;activeProfiles&gt;
+    &lt;activeProfile&gt;compiler&lt;/activeProfile&gt;
+  &lt;/activeProfiles&gt;
+&lt;/settings&gt;
+</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(&quot;&lt;toolchainType&gt;&quot;)</code> (for example 
<code>@Named(&quot;custom&quot;)</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 = &quot;${session}&quot;, 
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(&quot;custom&quot;, session);
+
+    if (toolchain == null) {
+        throw new MojoExecutionException(
+                &quot;Could not find 'custom' toolchain: please check 
maven-toolchains-plugin configuration.&quot;);
+    }
+
+    getLog().info(&quot;Found 'custom' toolchain in build context.&quot;);
+
+    // get a tool from the toolchain
+    String path = toolchain.findTool(&quot;tool&quot;);
+
+    getLog().info(&quot;Found expected tool named 'tool' at following 
location: &quot; + 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">&lt;plugin&gt;
+  &lt;groupId&gt;...&lt;/groupId&gt;
+  &lt;artifactId&gt;...&lt;/artifactId&gt;
+  &lt;version&gt;...&lt;/version&gt;
+  &lt;extensions&gt;true&lt;/extensions&gt;&lt;!-- to share the custom 
toolchain with maven-toolchains-plugin --&gt;
+&lt;/plugin&gt;
+</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">&lt;project&gt;
+  &lt;build&gt;
+    &lt;extensions&gt;
+      &lt;extension&gt;
+        &lt;groupId&gt;...&lt;/groupId&gt;
+        &lt;artifactId&gt;...&lt;/artifactId&gt;
+        &lt;version&gt;...&lt;/version&gt;
+      &lt;/extension&gt;
+    &lt;/extensions&gt;
+  &lt;/build&gt;
+&lt;/project&gt;
+</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/>

Reply via email to