Usage

Brief examples on how to use the Maven Toolchains Plugin.

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 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 this guide.

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 available toolchains.

That being said, you still need to configure the plugin in your pom.xml. 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.1.0</version>
        <configuration>
          <!-- Configure your toolchain requirements here -->
        </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.

Generic Plugin configuration information

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