Gradle Goodness: Java Toolchain Configuration Using User Defined Java Locations

With the java plugin we can configure a so-called Java toolchain. The toolchain configuration is used to define which Java version needs to be used to compile and test our code in our project. The location of the Java version can be determined by Gradle automatically. Gradle will look at known locations based on the operating system, package managers, IntellIJ IDEA installations and Maven Toolchain configuration.

But we can also define the locations of our Java installations ourselves using the project property org.gradle.java.installations.paths. We provide the paths to the local Java installations as a comma separated list as value for this property. When we set this property we can also disable the Gradle toolchain detection mechanism, so only the Java installations we have defined ourselves are used. To disable the automatic detection we set the property org.gradle.java.installations.auto-detect to false. If we leave the value to the default value true, then the locations we set via org.gradle.java.installations.paths are added to the Java installations already found by Gradle.

The property org.gradle.java.installations.paths is a project property we can set via the command line, but we can also set it in the gradle.properties file in our GRADLE_USER_HOME directory. Then the values we define will be used by all Gradle builds on our machine.

In the following example gradle.properties file we define the locations of two Java installations and also disable the automatic detection of Java installations. We store this file in our GRADLE_USER_HOME directory.

# File: $GRADLE_USER_HOME/gradle.properties
# We define the locations of two Java installations on our computer.
org.gradle.java.installations.paths=C:/Users/mrhaki/tools/apps/zulu11-jdk/current,C:/Users/mrhaki/tools/apps/zulu17-jdk/current

# We disable the automatic detection of Java installations by Gradle.
org.gradle.java.installations.auto-detect=false

# We also disable the automatic download of Java installations by Gradle.
org.gradle.java.installations.auto-download=false

We add the java plugin and configure our toolchain with the following Gradle build script:

// File: build.gradle.kts
plugins {
    java
}

java {
    toolchain {
        // We want to use Java 17 to compile, test and run our code.
        // Now it doesn't matter which Java version is used by Gradle itself.
        languageVersion = languageVersion.set(JavaLanguageVersion.of(17))
    }
}

We run the javaToolchains task to see the Java toolchain configuration:

$ ./gradlew javaToolchains

> Task :javaToolchains

 + Options
     | Auto-detection:     Disabled
     | Auto-download:      Disabled

 + Azul Zulu JDK 11.0.22+7-LTS
     | Location:           C:\Users\mrhaki\tools\apps\zulu11-jdk\current
     | Language Version:   11
     | Vendor:             Azul Zulu
     | Architecture:       amd64
     | Is JDK:             true
     | Detected by:        Gradle property 'org.gradle.java.installations.paths'

 + Azul Zulu JDK 17.0.10+7-LTS
     | Location:           C:\Users\mrhaki\tools\apps\zulu17-jdk\current
     | Language Version:   17
     | Vendor:             Azul Zulu
     | Architecture:       amd64
     | Is JDK:             true
     | Detected by:        Gradle property 'org.gradle.java.installations.paths'


BUILD SUCCESSFUL in 1s
1 actionable task: 1 executed

In the generated output we can see that Gradle detected the two Java installations we defined in the gradle.properties file using the Gradle property org.gradle.java.installations.paths.

Written with Gradle 8.5.