Creating a Custom Toolchain

A toolchain consists of:

• an interface extending org.apache.maven.toolchain.Toolchain,
• an implementation of this interface. Extending org.apache.maven.toolchain.DefaultToolchain is strongly encouraged, since its provides org.apache.maven.toolchain.ToolchainPrivate, which is an internal requirement,
• a org.apache.maven.toolchain.ToolchainFactory, provided as JSR-330 component annotated with @Named("<toolchainType>") (e.g. @Named("custom")) and @Singleton.

Creating a Plugin Using a Toolchain

To find a tool, a plugin uses ToolchainManager API to load the toolchain, then uses that toolchain object to find the tool's path:

    @Component
    private ToolchainManager toolchainManager;

    @Component
    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 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 an 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>

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