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-toolchains-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 07f806b Move the toolchains pages to the Maven site
07f806b is described below
commit 07f806bbc1290de0959bd039cc4a897be67dd525
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 19:59:02 2026 +0000
Move the toolchains pages to the Maven site
---
src/site/markdown/index.md | 2 +-
src/site/markdown/toolchains/custom.md | 109 ------------------------------
src/site/markdown/toolchains/index.md | 33 ----------
src/site/markdown/toolchains/jdk.md.vm | 117 ---------------------------------
src/site/markdown/usage.md.vm | 4 +-
src/site/site.xml | 3 -
6 files changed, 3 insertions(+), 265 deletions(-)
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index dfa97d0..249d6a6 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -39,7 +39,7 @@ Two associated helper goals are also provided:
-
[toolchains:display-discovered-jdk-toolchains](./display-discovered-jdk-toolchains-mojo.html)
displays discovered JDK toolchains to the console,
-
[toolchains:generate-jdk-toolchains-xml](./generate-jdk-toolchains-xml-mojo.html)
can be used to generate discovered JDKs in `toolchains.xml` format so the user
can copy and paste.
-The previous `toolchain` goal is still available for JDK and [other
types](./toolchains/custom.html) of toolchains:
+The previous `toolchain` goal is still available for JDK and [other
types](https://maven.apache.org/guides/mini/guide-using-toolchains.html#Custom_Toolchains)
of toolchains:
- [toolchains:toolchain](./toolchain-mojo.html) selects a toolchain from
`toolchains.xml` based on configured build requirements and stores it in build
context for later retrieval by other plugins.
## Usage
diff --git a/src/site/markdown/toolchains/custom.md
b/src/site/markdown/toolchains/custom.md
deleted file mode 100644
index da81777..0000000
--- a/src/site/markdown/toolchains/custom.md
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: Custom Toolchains
-author:
- - Hervé Boutemy
-date: 2014-11-08
----
-
-<!--
-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.
--->
-
-# 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](../scm.html):
-
-- See `src/it/setup-custom-toolchain` for the custom toolchain and plugin,
-- See `src/it/use-custom-toolchain` for a sample project using the toolchain
through its plugin.
-
-Following instructions are explanations of key points of the sample.
-
-## 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](https://maven.apache.org/maven-jsr330.html)
annotated with `@Named("<toolchainType>")` (e.g. `@Named("custom")`) and
`@Singleton`.
-## Creating a Plugin Using a Toolchain
-
-To find a tool, a plugin uses
[`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
- @Component
- private ToolchainManager toolchainManager;
-
- @Component
- private MavenSession session;
-
- 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 Maven
extension:
-
-- if the toolchain is packaged with the plugin, this is done by declaring 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,
it has to be declared 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 (eventually providing multiple
goals), it is simpler to package the toolchain with the plugin in a single
artifact.
diff --git a/src/site/markdown/toolchains/index.md
b/src/site/markdown/toolchains/index.md
deleted file mode 100644
index a761d80..0000000
--- a/src/site/markdown/toolchains/index.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: Standard Toolchains
-author:
- - Milos Kleint
-date: 2007-10-10
----
-
-<!--
-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.
--->
-
-# Standard Toolchains
-
-The following standard toolchains are included by default with Maven:
-
-- [JDK](./jdk.html) - Defines the location and identification of a Java
Development Kit
-
-You can also create and use your own custom toolchains by following the
[Custom Toolchains](./custom.html) instructions.
diff --git a/src/site/markdown/toolchains/jdk.md.vm
b/src/site/markdown/toolchains/jdk.md.vm
deleted file mode 100644
index 47afd12..0000000
--- a/src/site/markdown/toolchains/jdk.md.vm
+++ /dev/null
@@ -1,117 +0,0 @@
----
-title: JDK Toolchain
-author:
- - Milos Kleint
-date: 2014-11-02
----
-
-<!--
-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.
--->
-
-# JDK Toolchain
-
-Note that this page refers to hand-written JDK toolchains in
`~/.m2/toolchains.xml`. For a simpler setup, look at the [JDK discovery
mechanism](./jdk-discovery.html).
-
-Toolchain Description
----------------------
-
-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.
-- Other tokens 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.
-
-Sample `~/.m2/toolchains.xml` setup
------------------------------------
-
-```xml
-<toolchains>
- <toolchain>
- <type>jdk</type>
- <provides>
- <version>11</version>
- <vendor>temurin</vendor>
- <purpose>for_mevenide</purpose>
- </provides>
- <configuration>
-
<jdkHome>/Library/Java/JavaVirtualMachines/temurin-11.jdk/Contents/Home</jdkHome>
- </configuration>
- </toolchain>
- [...]
-</toolchains>
-```
-
-This defines a toolchain with version 11, vendor "temurin", and purpose
"for\_mevenide".
-
-A project can request this toolchain by specifying the type "jdk" and the
version "11". It can also use a version range that includes 11 like `[8, 17]`.
It can also ask for the vendor temurin, with or without version, or the purpose
"for\_mevenide".
-
-Toolchains Plugin Configuration
--------------------------------
-
-A project specifies a toolchain in the configuration of the
maven-toolchains-plugin like so:
-
-```xml
-<project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-toolchains-plugin</artifactId>
- <version>${project.version}</version>
- <executions>
- <execution>
- <goals>
- <goal>toolchain</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <toolchains>
- <jdk>
- <version>[1.8,)</version>
- </jdk>
- </toolchains>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
-</project>
-```
-
-In this example, the project is requesting any toolchain with type jdk that
has a version of 1.8 or greater. "`version`" accepts any [version range
definitions](/enforcer/enforcer-rules/versionRanges.html). If you want exactly
JDK 1.8 from the vendor temurin, the plugin would be configured like this:
-
-```xml
- <configuration>
- <toolchains>
- <jdk>
- <version>1.8</version>
- <vendor>temurin</vendor>
- </jdk>
- </toolchains>
- </configuration>
-```
-
-Aside from version, the definitions are opaque strings. Maven looks in
`toolchains.xml` for a toolchain that provides version=="1.8" and
vendor=="temurin". It does not know or care what these strings mean. It does
not, for instance, concern itself with whether the jdkHome configured by the
toolchain that satisfies version=="1.8" and vendor=="temurin" is JDK 8 from the
Temurin project, or JDK 21 from Oracle. The JDK toolchain only checks that the
directory exists.
-
-All conditions need to be satisfied to find a toolchain.
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index f512f83..b7a79e8 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -76,7 +76,7 @@ That being said, you still need to configure the plugin in
your `pom.xml` to sel
</project>
```
-You can read more about which standard toolchains are available
[here](./toolchains/index.html).
+You can read more about the JDK toolchain in the [Guide to Using
Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html#JDK_Toolchain).
When executing, output will show toolchain(s) selection, for example:
@@ -107,7 +107,7 @@ Toolchains available on the building machine are described
in `~/.m2/toolchains.
See [Toolchains Descriptor](/ref/current/maven-core/toolchains.html) for
details on its structure.
-You can read more about which elements standard toolchains propose
[here](./toolchains/index.html).
+You can read more about which elements the JDK toolchain proposes in the
[Guide to Using
Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html#JDK_Toolchain).
Generic Plugin configuration information
----------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index b84e30f..b0961f5 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -33,9 +33,6 @@ under the License.
</item>
<item name="Usage" href="usage.html">
<item name="JDK Discovery Mechanism"
href="toolchains/jdk-discovery.html"/>
- <item name="Standard Toolchains" href="toolchains/index.html"/>
- <item name="JDK Standard Toolchain" href="toolchains/jdk.html"/>
- <item name="Custom Toolchains" href="toolchains/custom.html"/>
</item>
<item name="License" href="https://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>