What is a toolchain?

A Toolchain is an object that Maven plugins can use to retrieve preconfigured tools (including location and other information).

Maven Toolchains Plugin can read which toolchains are available on the user's computer (as configured in ~/.m2/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 the 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 hardcoding absolute paths into the pom.xml and without configuring every plugin that require a path to JDK tools.

The toolchains:toolchain goal

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 selected toolchain(s).

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:

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-toolchains-plugin</artifactId>
        <version>3.2.0</version>
        <configuration>
          <!-- Configure your toolchain requirements here -->
          <toolchain-type>
            <param>expected value</param>
            ...
          </toolchain-type>
          ...
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>toolchain</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

You can read more about which standard toolchains are available here.

When executing, output will show toolchain(s) selection, for example:

[INFO] --- toolchains:3.2.0:toolchain (default) @ project ---
[INFO] Required toolchain: jdk [ version='11' ]
[INFO] Found matching toolchain for type jdk: JDK[/opt/jdk-11]

or fail if no toolchain was found matching expected requirements:

[INFO] --- toolchains:3.2.0:toolchain (default) @ project ---
[INFO] Required toolchain: jdk [ version='17' ]
[ERROR] No toolchain matched from 2 found for type jdk
[ERROR] Cannot find matching toolchain definitions for the following toolchain types:
jdk [ version='17' ]

The toolchains.xml Descriptor

Toolchains available on the building machine are described in ~/.m2/toolchains.xml:

• toolchain <type>,
• <provides> elements to describe toolchain characteristics that can later be matched from plugin, when multiple toolchains for one type are available,
• <configuration> elements to configure access the toolchain.

See Toolchains Descriptor for details on its structure.

You can read more about which elements standard toolchains propose here.

Generic Plugin configuration information

See the following links for information about including and configuring plugins in your project:

• Configuring Plugins
• Plugin Development
• Plugin Prefix