1. Introduction
Maven Toolchains lets us define and use specific tool versions—so we can, for example, build our project with a different JDK than the one running Maven itself.
In this article, we’ll walk through how to set up Maven Toolchains and explore some of the handy features it offers.
2. Setup
To use Maven Toolchains, we’ll start by setting up a toolchains.xml file that defines which tools we want to use and where they’re located on our build machine. In this case, we’ll use a specific JDK instead of the default one detected by Maven to build our project on our local development machine.
Let’s create the toolchains.xml file inside the .m2 directory:
$ cd ~/.m2/
$ touch toolchains.xml
Next, let’s define the JDK version we want to use to build our project, along with its location:
<?xml version="1.0" encoding="UTF-8"?>
<toolchains>
<toolchain>
<type>jdk</type>
<provides>
<version>24</version>
<vendor>liberica</vendor>
</provides>
<configuration>
<jdkHome>${env.HOME}/.sdkman/candidates/java/24.0.1.fx-librca/</jdkHome>
</configuration>
</toolchain>
</toolchains>
Next, let’s configure the build requirements in our project’s pom.xml file:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-toolchains-plugin</artifactId>
<version>1.1</version>
<executions>
<execution>
<goals>
<goal>toolchain</goal>
</goals>
</execution>
</executions>
<configuration>
<toolchains>
<jdk>
<version>24</version>
<vendor>liberica</vendor>
</jdk>
</toolchains>
</configuration>
</plugin>
<!-- ... -->
<plugins>
<build>
The Maven Toolchains Plugin sets the toolchain for toolchain-aware plugins in our project. When we build the project, Maven matches this requirement against the toolchains available on our local machine.
Let’s test our setup:
$ mvn clean compile
From the build logs, we can see that Maven detected our toolchain:
[INFO] --- toolchains:1.1:toolchain (default) @ maven-toolchains ---
[INFO] Required toolchain: jdk [ vendor='liberica' version='24' ]
[INFO] Found matching toolchain for type jdk: JDK[/<home-directory>/.sdkman/candidates/java/24.0.1.fx-librca/]
Next, let’s see how we can use Maven Toolchains with other custom tools.
Let’s configure the Maven Protocol Buffers Plugin to explore this use case.
In this instance, we want to use a specific version of the Protocol Buffers compiler (protoc) to generate our Java classes. Note: The protobuf-maven-plugin is no longer maintained and is shown here for illustrative purposes only.
First, let’s add another entry to our toolchains.xml file:
<toolchains>
<!-- ... -->
<toolchain>
<type>protobuf</type>
<provides>
<version>3.0.0</version>
</provides>
<configuration>
<protocExecutable>${env.HOME}/DevTools/protoc-3.0.0/bin/protoc</protocExecutable>
</configuration>
</toolchain>
</toolchains>
The protocExecutable points to the location of the protoc binaries. Next, we update our project’s pom.xml file:
<dependencies>
<!-- ... -->
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>3.19.4</version>
</dependency>
</dependencies>
Next, update the maven-toolchains-plugin and add the toolchain-aware protobuf-maven-plugin:
<build>
<plugins>
<!-- ... -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-toolchains-plugin</artifactId>
<version>1.1</version>
<executions>
<execution>
<goals>
<goal>toolchain</goal>
</goals>
</execution>
</executions>
<configuration>
<toolchains>
<!-- ... -->
<protobuf>
<version>3.0.0</version>
</protobuf>
</toolchains>
</configuration>
</plugin>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>0.6.1</version>
<extensions>true</extensions>
<executions>
<execution>
<goals>
<goal>compile</goal>
<goal>test-compile</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
The org.xolstice.maven.plugins:protobuf-maven-plugin is toolchain-aware, so it can use the toolchain set by the maven-toolchains-plugin.
Finally, we can define our addressbook.proto file and verify our setup:
syntax = "proto3";
option java_package = "com.baeldung";
option java_multiple_files = true;
option java_outer_classname = "AddressBookProtos";
message Address {
string street_address = 1;
string city = 2;
string state = 3;
string postal_code = 4;
}
message Contact {
string first_name = 1;
string last_name = 2;
string email = 3;
string phone_number = 4;
Address address = 5;
}
message AddressBook {
repeated Contact contacts = 1;
}
$ mvn clean compile
The Java source is generated, and the compilation log shows that Maven detected and used the toolchain:
[INFO] --- toolchains:1.1:toolchain (default) @ maven-toolchains ---
//...
[INFO] Required toolchain: protobuf [ version='3.0.0' ]
[INFO] Found matching toolchain for type protobuf: PROTOC[/<home-directory>/DevTools/protoc-3.0.0/bin/protoc]
[INFO]
[INFO] --- protobuf:0.6.1:compile (default) @ maven-toolchains ---
[INFO] Toolchain in protobuf-maven-plugin: PROTOC[/<home-directory>/DevTools/protoc-3.0.0/bin/protoc]
[INFO] Compiling 1 proto file(s) to /<home-directory>/workspace/baeldung/local/maven-modules/maven-toolchains/target/generated-sources/protobuf/java
4. Conclusion
In this tutorial, we explored Maven Toolchains and how they let us define specific tool versions for our builds, such as using a different JDK than the one running Maven. We configured a toolchains.xml file, updated our pom.xml with toolchain-aware plugins, and verified that Maven correctly detected and used the specified toolchain, ensuring consistent, reproducible builds across environments.
As always, the code is available over on GitHub.
