Custom Toolchains

You can create your own custom toolchains with plugins using them.

A full working sample is included in maven-toolchains-plugin ITs, which are part of the plugin source tree:

  • see src/it/custom-toolchain-plugin for the custom toolchain and plugin,
  • see src/it/use-custom-toolchain for a sample project using the toolchain through its plugin.

Following instructions are explanations of key points of the sample.

Creating Custom Toolchain

A toolchain consists in:

Creating a Plugin Using a Toolchain

To get a configured toolchain, a plugin uses ToolchainManager API to get expected toolchain, then some tool in the toolchain:

    @Component
    private ToolchainManager toolchainManager;

    @Parameter( defaultValue = "${session}", required = true, readonly = true )
    private MavenSession session;

    public void execute()
        throws MojoExecutionException
    {
        // get the custom toolchain
        CustomToolchain toolchain = (CustomToolchain) toolchainManager.getToolchainFromBuildContext( "custom", session );

        if ( toolchain == null )
        {
            throw new MojoExecutionException( "Could not find 'custom' toolchain: please check maven-toolchains-plugin configuration." );
        }

        getLog().info( "Found 'custom' toolchain in build context." );

        // get a tool from the toolchain
        String path = toolchain.findTool( "tool" );

        getLog().info( "Found expected tool named 'tool' at following location: " + path );
    }

This code uses Maven Plugin Tool Java 5 Annotations.

Using the Custom Toolchain and its Plugin

The custom toolchain implementation needs to be shared between the toolchain-aware plugin and maven-toolchains-plugin: this is done using Maven extension:

  • if the toolchain is packaged with the plugin, this is done by declaring the plugin as extension: 
          <plugin>
        <groupId>...</groupId>
        <artifactId>...</artifactId>
        <version>...</version>
        <extensions>true</extensions><!-- to share the custom toolchain with maven-toolchains-plugin -->
      </plugin>
  • if the toolchain is packaged separately, to be shared by multiple plugins, it has to be declared as a build extension: 
    <project>
  <build>
    <extensions>
      <extension>
        <groupId>...</groupId>
        <artifactId>...</artifactId>
        <version>...</version>
      </extension>
    </extensions>
  </build>
</project>

Notice that packaging a toolchain in its own artifact separate from plugin is only useful when there are multiple plugins using the toolchain. As it is expected in general that a custom toolchain will be used by only one plugin (eventually providing multiple goals), it is simpler to package the toolchain with the plugin in only one artifact.