------ Guide to Using Toolchains ------ Maria Odea Ching Dennis Lundberg ------ 2014-11-02 ------ ~~ Licensed to the Apache Software Foundation (ASF) under one ~~ or more contributor license agreements. See the NOTICE file ~~ distributed with this work for additional information ~~ regarding copyright ownership. The ASF licenses this file ~~ to you under the Apache License, Version 2.0 (the ~~ "License"); you may not use this file except in compliance ~~ with the License. You may obtain a copy of the License at ~~ ~~ http://www.apache.org/licenses/LICENSE-2.0 ~~ ~~ Unless required by applicable law or agreed to in writing, ~~ software distributed under the License is distributed on an ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY ~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Guide to Using Toolchains * What is Toolchains? The Maven Toolchains provide a way for plugins to discover what JDK (or other tools) are to be used during the build, without the need to configure them in each plugin nor in every <<>>, or forcing a precise location among every machine building the project. With Maven Toolchains applied to JDK toolchain, a project can now be built using a specific version of JDK independent from the one Maven is running with. Think how JDK versions can be set in IDEs like IDEA, NetBeans and Eclipse, or how you can compile with an older JDK from Maven running with a recent one. ** Prerequisites Toolchains will only work in Maven 2.0.9 and higher versions. For more details about its design and implementation, please see {{{http://cwiki.apache.org/confluence/display/MAVENOLD/Toolchains}Toolchains}}. Below are some plugins which are toolchain-aware, with the toolchain-type used: *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ || Toolchain type || <> || <> || <> *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{/plugins/maven-compiler-plugin/}maven-compiler-plugin}}>>> | 2.1 | Apache Maven *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{/plugins/maven-jarsigner-plugin/}maven-jarsigner-plugin}}>>> | 1.3 | Apache Maven *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{/plugins/maven-javadoc-plugin/}maven-javadoc-plugin}}>>> | 2.5 | Apache Maven *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{/plugins/maven-surefire-plugin/}maven-surefire-plugin}}>>> | 2.5 | Apache Maven *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{http://mojo.codehaus.org/animal-sniffer-maven-plugin/}animal-sniffer-maven-plugin}}>>> | 1.3 | Codehaus Mojo *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{http://mojo.codehaus.org/cassandra-maven-plugin/}cassandra-maven-plugin}}>>> | 0.7.0-1 | Codehaus Mojo *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{http://mojo.codehaus.org/exec-maven-plugin/}exec-maven-plugin}}>>> | 1.1.1 | Codehaus Mojo *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{http://mojo.codehaus.org/jasperreports-maven-plugin/}jasperreports-maven-plugin}}>>> | 1.0-beta-3-SNAPSHOT | Codehaus Mojo *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{http://mojo.codehaus.org/jdiff-maven-plugin/}jdiff-maven-plugin}}>>> | 1.0-beta-1-SNAPSHOT | Codehaus Mojo *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | jdk | <<<{{{http://mojo.codehaus.org/keytool-maven-plugin/}keytool-maven-plugin}}>>> | 1.4 | Codehaus Mojo *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ | protobuf | <<<{{{http://sergei-ivanov.github.io/maven-protoc-plugin/examples/protobuf-toolchain.html}maven-protoc-plugin}}>>> | 0.3.2 | github *-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ * Using Toolchains in Your Project There are two essential components that you need to configure in order to use toolchains: [[1]] the <<<{{{/plugins/maven-toolchains-plugin/}maven-toolchains-plugin}}>>> in your project POM, [[2]] the <<<{{{/ref/current/maven-core/toolchains.html}toolchains.xml}}>>> file on the building machine. [] The <<>> is the one that sets the toolchain to be used by the toolchain-aware plugins in your project. For example, you want to use a different JDK version to build your project than the version used to run Maven, you can configure the version you want to use via this plugin as shown in the <<>> below: +-----+ ... org.apache.maven.plugins maven-compiler-plugin 3.1 org.apache.maven.plugins maven-toolchains-plugin 1.1 toolchain 1.5 sun ... +-----+ As you can see in the example above, a JDK toolchain with <<<\>>> "1.5" and <<<\>>> "sun" is to be used. Now how does the plugin know where this JDK is installed? This is where the <<>> file comes in. The <<>> file (see below) is the configuration file where you set the installation paths of your toolchains. This file should be put in your <<<${user.home}/.m2>>> directory. When the <<>> executes, it looks for the <<>> file, reads it and looks for a toolchain matching the toolchains requirements configured in the plugin. In our example, that would be a JDK toolchain with <<<\>>> "1.5" and <<<\>>> "sun". Once a match is found, the plugin then stores the toolchain to be used in the MavenSession. As you can see in our <<>> below, there is indeed a JDK toolchain with <<<\>>> "1.5" and <<<\>>> "sun" configured. So when the <<>> we've configured in our <<>> above executes, it will see that a JDK toolchain is set in the MavenSession and will thereby use that toolchain (that would be the JDK installed at <<>> for our example) to compile the sources. +-----+ jdk 1.5 sun /path/to/jdk/1.5 jdk 1.6 sun /path/to/jdk/1.6 netbeans 5.5 /path/to/netbeans/5.5 +-----+ Note that you can configure as many toolchains as you want in your <<>> file.