You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2024/03/02 18:05:33 UTC
(maven-toolchains-plugin) branch rework created (now aec31d5)
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a change to branch rework
in repository https://gitbox.apache.org/repos/asf/maven-toolchains-plugin.git
at aec31d5 rework documentation
This branch includes the following new commits:
new aec31d5 rework documentation
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-toolchains-plugin) 01/01: rework documentation
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch rework
in repository https://gitbox.apache.org/repos/asf/maven-toolchains-plugin.git
commit aec31d5b9950a12190e9f105cd5b8bdaae165bc6
Author: Hervé Boutemy <hb...@apache.org>
AuthorDate: Sat Mar 2 19:05:22 2024 +0100
rework documentation
---
src/site/apt/index.apt.vm | 5 +++--
src/site/apt/toolchains/jdk.apt.vm | 21 ++++++++++----------
src/site/apt/usage.apt.vm | 40 +++++++++++++++++++++++++++++---------
src/site/site.xml | 8 ++++++--
4 files changed, 50 insertions(+), 24 deletions(-)
diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm
index 95b810e..b5bf949 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -25,15 +25,16 @@
${project.name}
- The Toolchains Plugins enables sharing configuration across plugins,
+ The Toolchains Plugins enables sharing configuration about tools across plugins,
for example to make sure the plugins like compiler, surefire, javadoc, webstart etc. all use the same JDK for execution independently from JRE used to run Maven itself.
+
Similarly to the maven-enforcer-plugin, it allows you to control environmental constraints in the build.
* Goals Overview
The Toolchains plugin has one goal:
- * {{{./toolchain-mojo.html}toolchains:toolchain}} selects a toolchain based on configured requirements and stores it in build context for later retrieval by other plugins.
+ * {{{./toolchain-mojo.html}toolchains:toolchain}} selects a toolchain based on configured build requirements and stores it in build context for later retrieval by other plugins.
* Usage
diff --git a/src/site/apt/toolchains/jdk.apt.vm b/src/site/apt/toolchains/jdk.apt.vm
index 7d48109..c16b2b7 100644
--- a/src/site/apt/toolchains/jdk.apt.vm
+++ b/src/site/apt/toolchains/jdk.apt.vm
@@ -26,21 +26,19 @@
JDK Toolchain
-* Toolchain Identification
+* Toolchain Description
The toolchain type id for JDK is "<<<jdk>>>".
- Predefined identification tokens, for requirement matching, are:
+ Predefined <<<\<provides\>>>> identification tokens, for requirement matching in plugin configuration, are:
- * "<<<version>>>" marks the version of the JDK. This can be either a single version or a version range.
+ * "<<<version>>>" marks the version of the JDK in <<<toolchain.xml>>>. In plugin's selection, this can be either a single version or a version range.
- * Other tokens are accepted, but only exact matches are supported.
+ * Other tokens are accepted, but only exact matches are supported.
- []
+ []
-* Toolchain Configuration
-
- There is only one configuration element named "<<<jdkHome>>>". It designates the root directory
+ There is only one <<<toolchains.xml>>> <<<\<configuration\>>>> element named "<<<jdkHome>>>". It designates the root directory
of a JDK installation.
* Sample <<<toolchains.xml>>> setup
@@ -63,14 +61,15 @@ JDK Toolchain
+---+
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
+ 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 configuraiton of the maven-toolchains-plugin like so:
+ A project specifies a toolchain in the configuration of the maven-toolchains-plugin like so:
+---+
<project>
@@ -117,7 +116,7 @@ JDK Toolchain
</configuration>
+---+
- Aside from version, the definitions are opaque strings. Maven looks in toolchains.xml
+ 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,
diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm
index 59ad102..4ca5fa4 100644
--- a/src/site/apt/usage.apt.vm
+++ b/src/site/apt/usage.apt.vm
@@ -36,10 +36,11 @@ Usage
Maven Toolchains Plugin can read which toolchains are available on the user's
computer (as configured in <<<toolchains.xml>>>) and match them against the
toolchain requirements of the project (as configured in <<<pom.xml>>>). If a
- match is found, the toolchain is made available to other, toolchain aware,
- Maven plugins in the build. A list of which plugins are toolchain aware can be
- found in
- {{{http://maven.apache.org/guides/mini/guide-using-toolchains.html}this guide}}.
+ match is found, the toolchain is made available to other, <toolchain aware>,
+ Maven plugins in the build.
+
+ A list of which plugins are <toolchain aware> can be found in the
+ {{{/guides/mini/guide-using-toolchains.html}Guide to Using Toolchains}}.
With the <<<jdk>>> toolchain, for example, instead of being stuck with the JDK
used to run Maven, all plugins can use the same other JDK instance without
@@ -50,10 +51,10 @@ Usage
This goal is bound by default to the <<<validate>>> lifecycle phase, the
first phase in the lifecycle. This is necessary so that all the plugins that
- are bound to later lifecycle phases are made aware of the available
- toolchains.
+ are bound to later lifecycle phases are made aware of the selected
+ toolchain(s).
- That being said, you still need to configure the plugin in your <<<pom.xml>>>.
+ That being said, you still need to configure the plugin in your <<<pom.xml>>> to select expected toolchain(s).
In order for it to execute, you need to add an execution for it, like this:
+---+
@@ -66,6 +67,11 @@ Usage
<version>${project.version}</version>
<configuration>
<!-- Configure your toolchain requirements here -->
+ <toolchain-type>
+ <param>expected value</param>
+ ...
+ </toolchain-type>
+ ...
</configuration>
<executions>
<execution>
@@ -80,8 +86,24 @@ Usage
</project>
+---+
- You can read more about which standard toolchains are available
- {{{./toolchains/index.html}here}}.
+ You can read more about which standard toolchains are available {{{./toolchains/index.html}here}}.
+
+* The <<<toolchains.xml>>> Descriptor
+
+ Tools available on the building machine are described in <<<~/.m2/toolchains.xml>>>:
+
+ * tool <<<\<type\>>>>,
+
+ * <<<\<provides\>>>> elements to describe tool characteristics that can later be matched from plugin, when multiple
+ tools for on <<<type>>> are available,
+
+ * <<<\<configuration\>>>> elements to access the tool.
+
+ []
+
+ See {{{/ref/3.9.6/maven-core/toolchains.html}Toolchains Descriptor}} for details on its structure.
+
+ You can read more about which elements standard toolchains propose {{{./toolchains/index.html}here}}.
* Generic Plugin configuration information
diff --git a/src/site/site.xml b/src/site/site.xml
index 4e679ac..f438315 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -19,9 +19,9 @@ specific language governing permissions and limitations
under the License.
-->
-<project xmlns="http://maven.apache.org/DECORATION/1.4.0"
+<project xmlns="http://maven.apache.org/DECORATION/1.8.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/DECORATION/1.4.0 https://maven.apache.org/xsd/decoration-1.4.0.xsd">
+ xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.1 https://maven.apache.org/xsd/decoration-1.8.1.xsd">
<body>
<menu name="Overview">
<item name="Introduction" href="index.html"/>
@@ -36,5 +36,9 @@ under the License.
<item name="License" href="https://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>
</menu>
+ <menu name="See Also">
+ <item name="Guide to Using Toolchains" href="/guides/mini/guide-using-toolchains.html"/>
+ <item name="Toolchains Descriptor" href="/ref/current/maven-core/toolchains.html"/>
+ </menu>
</body>
</project>