Toolchains

Goal

Have a way for plugins to discover what JDK (or other tools) are to
be used, without configuring the plugins. The current Maven way of
achieving this is to run Maven itself with the required JDK. After
toolchains, the JDK that Maven is running within, shall be irrelevant
to the project in question.

Motivation

Current way or enforcing project's JDK version (via the enforcer or
otherwise) by forcing the user to run Maven itself with the given JDK
version breaks embedded use.
Additionally toolchains will allow a type of user interaction that IDE
users are used to. Just set the JDK to the project and go.

Types of toolchains

Design

Note: I'll be focusing on JDK toolchain. I don't have enough
background information for other types of toolchains.
The associated issue is: MNG-468

3 basic points of view:

1. Plugin denotes what toolchain type it requires for it's
operation. So compilation, surefire, jnlp, ... need a JDK toolchain
instance for example. The actual instance of the toolchain is passed
into the plugin by the infrastructure (using Build context in current implementation).
Most current plugins that use JDK for processing, use the maven's JDK instance by default. The only change introduced is
to use the toolchain in the BuildContext if found. If not, do as we did so far.

Q1: how shall the plugin tell what toolchains it needs? parameter?
parameter's or mojo's @toolchain annotation? The actual retrieval of the toolchain from build content can be done completely behind the scenes, so marking the plugin as toolchain-aware is primarily documentation oriented.

2. User defines the toolchain instances that are available in his
current setup. Shall be user based, project independent, stored in
$HOME/.m2/toolchains.xml file.
Example toolchains.xml file:

<toolchains>
    <toolchain>
       <type>jdk</type>
       <provides>
           <version>1.5</version>
           <vendor>sun</vendor>
           <id>for_mevenide</id>
       </provides>
       <configuration>
          <jdkHome>/home/mkleint/javatools/jdk</jdkHome>
       </configuration>
    </toolchain>
    <toolchain>
       <type>jdk</type>
       <provides>
           <version>1.6.0</version>
       </provides>
       <configuration>
          <jdkHome>/home/mkleint/javatools/jdk1.6.0</jdkHome>
       </configuration>
    </toolchain>
</toolchains>

3. Project shall be allowed to state which instance of the given
toolchain type it requires for the build. Therefore making sure that
all plugins use jdk15 for example.
if such toolchain instance is not found in user's local setup, the
build shall fail early.
For this purpose a new plugin (maven-toolchain-plugin) is introduced.
It is responsible for matching the correct
toolchain instances from the user's setup against the requirements of the project and make it available for other plugins to use (in the build
context).

<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.4)</version>
              <!--vendor>sun</vendor-->
          </jdk>
        </toolchains>
  </configuration>
</plugin>

The process of matching required toolchain against the provided ones is following.

1. Get all toolchains for a given type (eg. jdk)
2. go through them one by one and try match the requirements in the toolchain-plugin configuration against the provided tokens. Some like 'version' are to be specially handled and allow for range matching etc, the rest is exact match only. The creator of the particular type of toolchain can define the specially handled tokens.
3. first successful match is pushed into the maven build environment (BuildContext) for use by other plugins down the road
4. if there are no matches, the build fails.

Backward compatibility

Can we achieve backward compatibility with 2.0.x or do we have to go with 2.1 only? It would be nice if at least plugins that start using toolchains would not require 2.1.
The only roadblock for backward compatibility is the build-context that is needed for inter-plugin communication. Build-context seems to be relatively independent of the rest of maven, just requires plexus container that is newer than the one used in 2.0.x. Can we upgrade?

Implementation

The feature is developed mainly on trunk. toolchains components toolchains plugin
Only the changes to existing plugins are on branch.

after compiling, make sure you put the jar with toolchain components into the 2.1-SNAPSHOT maven binary, into the lib/ subfolder.
Attached is sample project and toolchain definition.