back to all blogsSee all blog posts

Support for Java Toolchains in Liberty Build Plugins

image of author
Arun Venmany on Mar 2, 2026
Post available in languages:

Liberty Gradle and Maven plugins now support Java Toolchains. This feature allows you to decouple the JDK used to run your build tool (Gradle or Maven) from the JDK used to compile your code and run your Liberty server and applications.

When a toolchain is configured, the Liberty build plugins automatically detect the specified JDK and use it to start the Liberty server, ensuring environment consistency across your development team.

Why use Java Toolchains?

Using Java toolchains provides several advantages for enterprise development and CI/CD pipelines:

  • Environment Consistency: Ensure every developer and build server uses the exact same JDK version for the runtime, regardless of what is installed as the system default.

  • Decoupling: You can run your build tool (e.g., Maven or Gradle) on a newer, high-performance JVM while targeting an older JDK (like Java 8 or 11) for the actual Liberty server.

  • Simplified Configuration: Avoid manually setting and maintaining JAVA_HOME environment variables across different machines. The build tool handles the discovery and provisioning of the required JDK.

  • Early Detection: If a developer tries to build a project but lacks the required JDK version, the build tool will provide a clear error or automatically download the correct version (depending on your configuration).

Minimum Version Requirements

To use toolchain support, ensure you are using the following plugin versions or newer:

  • Liberty Maven Plugin: 3.12.0

  • Liberty Gradle Plugin: 3.10.0

Liberty Gradle Plugin Support

The Liberty Gradle plugin integrates with the standard Gradle Java Toolchain feature. It does not require a Liberty-specific configuration block; it automatically honors the project’s java { toolchain { …​ } } settings.

How to use

Apply the java plugin and define the desired Java version in your build.gradle file:

plugins {
    id 'java'
    id 'io.openliberty.tools.gradle.Liberty' version '3.10.0'
}

java {
    toolchain {
        // Required Java version for your project
        languageVersion = JavaLanguageVersion.of(17)
        // Optional: include vendor if you need to distinguish between toolchains
        // vendor.set(JvmVendorSpec.ADOPTIUM)
    }
}

Liberty Maven Plugin Support

By leveraging Maven Toolchains, the Liberty Maven plugin can decouple the JDK used to run the plugin from the JDK used to run your Liberty server. It retrieves these definitions from your local toolchains.xml.

How to use

  1. Configure toolchains.xml: Ensure your ~/.m2/toolchains.xml defines the JDKs available on your system.

  2. Update pom.xml: Configure the plugin versions in your liberty-maven-plugin configurations and add a <jdkToolchain> configuration.

<plugin>
    <groupId>io.openliberty.tools</groupId>
    <artifactId>liberty-maven-plugin</artifactId>
    <version>3.12.0</version>
    <configuration>
        <jdkToolchain>
            <version>11</version>
             <!-- Optional: include vendor if you need to distinguish between toolchains -->
             <!-- <vendor>ibm</vendor> -->
        </jdkToolchain>
    </configuration>
</plugin>

Dev mode behavior

When you run gradle libertyDev or mvn liberty:dev, the plugin ensures environment consistency by applying the following logic:

  • Server JVM: Sets the Liberty server process’s JAVA_HOME to the configured toolchain JDK.

  • Recompilation: Automatically uses the toolchain JDK for compilation (e.g., compileJava and compileTestJava tasks in Gradle, or compiler:compile and compiler:testCompile goals in Maven).

  • Logs: Look for confirmation in the terminal output to verify the toolchain is active:

Gradle

CWWKM4101I: The :libertyDev task is using the configured toolchain JDK located at /path/to/jdk-17
Maven

CWWKM4101I: The liberty:dev goal is using the configured toolchain JDK located at /path/to/jdk-17

Rules and precedence

Both plugins follow a specific order of operations:

  1. Manual Overrides: If JAVA_HOME is set in server.env or jvm.options, that value takes precedence over the Java toolchain.

  2. Toolchain Resolution: If no manual override exists, the plugin uses the resolved toolchain JDK.

  3. Fallback: If no toolchain is found, the plugin falls back to the JVM currently running the build.

Verification

To confirm which JDK the Liberty server started with, check the messages.log file (located in ${server.output.dir}/logs/). You should see entries similar to the following:

********************************************************************************
product = Open Liberty 25.0.0.12 (wlp-1.0.108.cl251220251117-0302)
wlp.install.dir = /path/to/project/build/wlp/
java.home = /path/to/java/semeru-11.0.28/Contents/Home
java.version = 11.0.28
java.runtime = IBM Semeru Runtime Open Edition (11.0.28+6)
os = Mac OS X (26.1; aarch64) (en_IN)
process = [email protected]
Classpath = /path/to/project/build/wlp/bin/tools/ws-server.jar
Java Library path = /path/to/java/semeru-11.0.28/Contents/Home/lib/default:/path/to/java/semeru-11.0.28/Contents/Home/lib:/usr/lib
********************************************************************************

Conclusion

With Java toolchain support in the Liberty Gradle and Maven plugins, managing your development environment becomes significantly more robust. By defining your Java version at the project level, you eliminate the "it works on my machine" class of bugs related to mismatched JDKs. Whether you are using Gradle’s automatic provisioning or Maven’s toolchain manager, your Liberty server will now stay in perfect sync with your source code’s requirements.

Further Documentation

For detailed technical specifications, refer to the toolchains.md documentation in the plugin repositories:

Reporting Issues

We welcome feedback and contributions! If you encounter any bugs or have feature requests, please report them in our open-source repositories: