~~ 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.

  ------
  Usage
  ------
  Milos Kleint
  Dennis Lundberg
  ------
  2014-11-02
  ------

Usage

  Brief examples on how to use the Maven Toolchains Plugin.

* What is a toolchain?

  A Toolchain is an object that Maven plugins can use to retrieve preconfigured
  tools (including location and other information).

  Maven Toolchains Plugin can read which toolchains are available on the user's
  computer (as configured in <<<toolchains.xml>>>) and match them against the
  toolchain requirements of the project (as configured in <<<pom.xml>>>). If a
  match is found, the toolchain is made available to other, toolchain aware,
  Maven plugins in the build. A list of which plugins are toolchain aware can be
  found in
  {{{http://maven.apache.org/guides/mini/guide-using-toolchains.html}this guide}}.

  With the <<<jdk>>> toolchain, for example, instead of being stuck with the JDK
  used to run Maven, all plugins can use the same other JDK instance without
  hardcoding absolute paths into the <<<pom.xml>>> and without configuring every
  plugin that require a path to JDK tools.

* The <<<toolchains:toolchain>>> goal

  This goal is bound by default to the <<<validate>>> lifecycle phase, the
  first phase in the lifecycle. This is necessary so that all the plugins that
  are bound to later lifecycle phases are made aware of the available
  toolchains.

  That being said, you still need to configure the plugin in your <<<pom.xml>>>.
  In order for it to execute, you need to add an execution for it, like this:

+---+
<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-toolchains-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <!-- Configure your toolchain requirements here -->
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>toolchain</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
+---+

  You can read more about which standard toolchains are available
  {{{./toolchains/index.html}here}}.

* Generic Plugin configuration information

  See the following links for information about including and configuring plugins in your project:

  * {{{http://maven.apache.org/guides/mini/guide-configuring-plugins.html}Configuring Plugins}}

  * {{{http://maven.apache.org/guides/plugin/guide-java-plugin-development.html}Plugin Development}}

  * {{{http://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html}Plugin Prefix}}

   []