Toolchains for Maven Plugins

The Maven Toolchains provide a way for for plugins to discover the tools (such as JDK) to be used when building without the need to configure the tools. This allows a project to be built using a specific version of a tool independent from the one Maven is running with.

Below are the plugins that are toolchain-aware. Please take note that these are still in the SNAPSHOT versions and are not yet released.

• maven-compiler-plugin-2.1-SNAPSHOT
• maven-javadoc-plugin-2.5-SNAPSHOT
• maven-surefire-plugin-2.5-SNAPSHOT
• exec-maven-plugin-1.1.1-SNAPSHOT

Using Toolchains in Projects

There are two essential components that needs to be configured when using the Maven Toolchains namely maven-toolchains-plugin and toolchains.xml file.
The maven-toolchains-plugin sets the toolchain to be used by the toolchain-aware plugins in the project. You can configure in the project’s pom.xml file the version of the tool you want to use using this plugin as shown below.

<plugins>
    ...
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.1-SNAPSHOT</version>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-toolchains-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
        <executions>
            <execution>
                <phase>validate</phase>
                <goals>
                    <goal>toolchain</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <toolchains>
                <jdk>
                    <version>1.5</version>
                    <vendor>sun</vendor>
                </jdk>
            </toolchains>
        </configuration>
        <plugin>
        ...
</plugins>

The toolchain.xml file is a configuration file containing as many installation paths of toolchains as you want. This file should be put in [user_home]\.m2\ directory. This is how the file looks like:

<?xml version="1.0" encoding="UTF8"?>
<toolchains>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.5</version>
            <vendor>sun</vendor>
            <id>default</id>
        </provides>
        <configuration>
            <jdkHome>/path/to/jdk/1.5</jdkHome>
        </configuration>
    </toolchain>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.6</version>
            <vendor>sun</vendor>
            <id>ide</id>
        </provides>
        <configuration>
            <jdkHome>/path/to/jdk/1.6</jdkHome>
        </configuration>
    </toolchain>
    <toolchain>
        <type>netbeans</type>
        <provides>
            <version>5.5</version>
        </provides>
        <configuration>
            <installDir>/path/to/netbeans/5.5</installDir>
        </configuration>
    </toolchain>
</toolchains>

When the maven-toolchains-plugin executes, the maven-toolchain component used by the plugin will refer to the toolchain.xml file for the path of the toolchain configured in the plugin. Once a match is found, the plugin then sets the toolchain to be used in the MavenSession.