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.2.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.