Gradle Toolchains Support for JVM Projects

1. Introduction

In this tutorial, we’re going to explore Gradle toolchains support for JVM Projects.

We’ll first understand the motivation behind this feature. Then, we’ll define it and give it a try with practical examples.

2. Reasoning Behind Toolchains

Before discussing what a toolchain is, we need to talk about the reasons why it exists. Let’s say that we want to write a Java project. Our Java project will probably contain some tests. So at least we would want to compile our code and run the tests. We add our java built-in Gradle plugin and specify the bytecode version we want:

plugins {
    id 'java'
}

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

Moreover, we can tell Gradle to compile our test classes into different bytecode versions if needed:

tasks {
    compileTestJava {
        sourceCompatibility = JavaVersion.VERSION_1_7
        targetCompatibility = JavaVersion.VERSION_1_7
    }
}

So far, so good. The only nuance is that to compile our sources/test classes, Gradle used its own JDK, i.e. the same JDK it runs on. We can work this around, though, by specifying the exact executable to be used:

compileTestJava.getOptions().setFork(true)
compileTestJava.getOptions().getForkOptions().setExecutable('/home/mpolivaha/.jdks/corretto-17.0.4.1/bin/javac')

compileJava.getOptions().setFork(true)
compileJava.getOptions().getForkOptions().setExecutable('/home/mpolivaha/.jdks/corretto-17.0.4.1/bin/javac')

However, the problem occurs if we use various JDKs during the build process.

For instance, assume we must test our Java app on our customers’ JDKs before release. These JDKs might be from different vendors and, though complying with spec, be different in details. And we can theoretically solve this without toolchains, but it would be a much more complicated solution. Toolchains make the config of builds easier, which require various JDKs for different purposes.

3. Toolchains Definition

Starting from version 6.7, Gradle introduced the JVM Toolchains feature. The notion toolchain is not new, though. As such, it existed in Maven for quite some time. In general, a toolchain is a set of tools and binaries that are required to build, test and run the software. So, in Java, we can say that JDK is the Java toolchain since it allows compiling, testing and running the Java program.

We can define the toolchain at a project level, so in this case, it’ll look like this:

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
        vendor = JvmVendorSpec.AMAZON
        implementation = JvmImplementation.VENDOR_SPECIFIC
    }
}

Thus, we can specify the Java version needed, the vendor of JDK, and the particular implementation of JVM of this vendor. For the toolchain spec to be correct, we at least must set the version.

What Gradle would do when dealing with toolchains is simple. First, it will try to find the requested toolchain locally; there is a specific algorithm for this. If Gradle doesn’t find the required toolchains locally, it’ll try to find it remotely and download it. If Gradle cannot find the required toolchain remotely, the build fails.

It is also worth mentioning that sometimes we would want to disable auto-provisioning. We can do so by passing -Porg.gradle.java.installations.auto-download=false into gradle executable. In this case, the Gradle build would fail if the toolchain couldn’t be found locally.

4. Toolchains on Task Level

The real power of toolchains unleashes with the ability to specify the JDK installation per task manner:

tasks.named('compileJava').get().configure {
    javaCompiler = javaToolchains.compilerFor {
        languageVersion = JavaLanguageVersion.of(17)
        vendor = JvmVendorSpec.AMAZON
        implementation = JvmImplementation.VENDOR_SPECIFIC
    }
}

tasks.register("testOnAmazonJdk", Test.class, {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
        vendor = JvmVendorSpec.AMAZON
    }
})

tasks.named("testClasses").get().finalizedBy("testOnAmazonJdk")

In this example above, we configured the compileJava task to run on Oracle JDK 15. We also created testOnAmazonJdk task, that would run right after the testClasses task. Notice that this new task is executed on a separate JDK as well.

5. Local Toolchain Identification

Lastly, Gradle allows us to view local installations of toolchains available to the current project by using the following command:

gradle javaToolchains

First, Gradle will search for the build file in the current location. Then it will list toolchains found according to locations/rules specified in the build file.

6. Conclusion

In this quick tutorial, we have reviewed the Gradle toolchains feature. This feature simplifies working with different JDKs during the build process, if applicable. It is available from Gradle 6.7, and we can apply it on task level, which makes this feature really valuable.