src/site/markdown/usage.md.vm

---
title: Usage
author: 
  - Milos Kleint
  - Dennis Lundberg
date: 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.
-->

# Usage

Brief examples on how to use the Maven Toolchains Plugin.

What is a toolchain?
--------------------

A [Toolchain](/ref/current/maven-core/apidocs/org/apache/maven/toolchain/Toolchain.html) 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 `~/.m2/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 the [Guide to Using Toolchains](/guides/mini/guide-using-toolchains.html).

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 requires 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 selected toolchain(s).

That being said, you still need to configure the plugin in your `pom.xml` to select expected toolchain(s). In order for it to execute, you need to add an execution for it, like this:

```xml
<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 -->
          <toolchain-type>
            <param>expected value</param>
            ...
          </toolchain-type>
          ...
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>toolchain</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
```

You can read more about which standard toolchains are available [here](./toolchains/index.html).

When executing, output will show toolchain(s) selection, for example:

```
[INFO] --- toolchains:${project.version}:toolchain (default) @ project ---
[INFO] Required toolchain: jdk [ version='11' ]
[INFO] Found matching toolchain for type jdk: JDK[/opt/jdk-11]
```

or fail if no toolchain was found matching expected requirements:

```
[INFO] --- toolchains:${project.version}:toolchain (default) @ project ---
[INFO] Required toolchain: jdk [ version='17' ]
[ERROR] No toolchain matched from 2 found for type jdk
[ERROR] Cannot find matching toolchain definitions for the following toolchain types:
jdk [ version='17' ]
```

The `toolchains.xml` Descriptor
-------------------------------

Toolchains available on the building machine are described in `~/.m2/toolchains.xml`:

- toolchain `<type>`,
- `<provides>` elements to describe toolchain characteristics that can later be matched from plugin, when multiple toolchains for one `type` are available,
- `<configuration>` elements to configure access the toolchain.

See [Toolchains Descriptor](/ref/current/maven-core/toolchains.html) for details on its structure.

You can read more about which elements standard toolchains propose [here](./toolchains/index.html).

Generic Plugin configuration information
----------------------------------------

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

- [Configuring Plugins](http://maven.apache.org/guides/mini/guide-configuring-plugins.html)
- [Plugin Development](http://maven.apache.org/guides/plugin/guide-java-plugin-development.html)
- [Plugin Prefix](http://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html)