Apache

Docs Plugins

Toolchains Plugin 3.3.0 · Other versions

The Toolchains Plugins allows to share configuration across plugins. For example to make sure the plugins like compiler, surefire, javadoc, webstart etc. all use the same JDK for execution.

Source
Edit this page
Wrong?
Report a problem

Custom Toolchains

You can create custom toolchains to use with standard plugins (such as the maven-compiler-plugin) or with custom plugins.

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

  • See src/it/setup-custom-toolchain 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 a Custom Toolchain

A toolchain consists of:

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.