Apache

Docs Plugins

Toolchains Plugin 3.3.0 · Other versions

The Toolchains Plugins allows to share configuration across plugins. For example to make sure the plugins like compiler, surefire, javadoc, webstart etc. all use the same JDK for execution.

Source
Edit this page
Wrong?
Report a problem

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.

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 plugin's selection, this can be either a single version or a version range.
  • Other tokens are accepted, but only exact matches are supported.

In toolchains.xml, there is only one <configuration> element named "jdkHome". It designates the root directory of a JDK installation.

Sample ~/.m2/toolchains.xml setup

<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:

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-toolchains-plugin</artifactId>
        <version>3.3.0</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. If you want exactly JDK 1.8 from the vendor temurin, the plugin would be configured like this:

        <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. JDK toolchain only checks that directory exists.

All conditions need to be satisfied to find a toolchain.