# Toolchains for JVM projects

version 7.0.2

By default, Gradle uses the same Java version for running Gradle itself and building JVM projects.

This is not always desirable. Building projects with different Java versions on different developer machines and CI servers may lead to unexpected issues. Additionally, you may want to build a project using a Java version that is not supported for running Gradle.

A Java Toolchain (from now on referred to simply as toolchain) is a set of tools, usually taken from a local JRE/JDK installation that are used to configure different aspects of a build. Compile tasks may use `javac` as their compiler, test and exec tasks may use the `java` command while `javadoc` will be used to generate documentation.

## Consuming Toolchains

A build can globally define what toolchain it targets by stating the Java Language version it needs and optionally the vendor:

buildSrc/src/main/groovy/myproject.java-conventions.gradle

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(11)
        }
    }

buildSrc/src/main/kotlin/myproject.java-conventions.gradle.kts

    java {
        toolchain {
            languageVersion.set(JavaLanguageVersion.of(11))
        }
    }

Executing the build (e.g. using `gradle check`) will now handle several things for you and others running your build

1. Setup all compile, test and javadoc tasks to use the defined toolchain which may be different than the one Gradle itself uses

2. Gradle detects locally installed JVMs

3. Gradle chooses a JRE/JDK matching the requirements of the build (in this case a JVM supporting Java 11)

4. If no matching JVM is found, it will automatically download a matching JDK from AdoptOpenJDK

| Toolchain support is only available in the Java plugins and for the tasks they define. For the Groovy plugin, compilation is supported but not yet Groovydoc generation. Support for the Scala plugin will be released later. However, running tests can leverage the toolchain support since the `Test` task does support toolchains.

### Using toolchains by specific vendors

In case your build has specific requirements from the used JRE/JDK, you may want to define the vendor for the toolchain as well. `JvmVendorSpec` has a list of well-known JVM vendors recognized by Gradle. The advantage is that Gradle can handle any inconsistencies across JDK versions in how exactly the JVM encodes the vendor information.

build.gradle

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(11)
            vendor = JvmVendorSpec.ADOPTOPENJDK
        }
    }

build.gradle.kts

    java {
        toolchain {
            languageVersion.set(JavaLanguageVersion.of(11))
            vendor.set(JvmVendorSpec.ADOPTOPENJDK)
        }
    }

If the vendor you want to target is not a known vendor, you can still restrict the toolchain to those matching the `java.vendor` system property of the available toolchains.

Given the snippet below, only toolchain are taken into accounts whose `java.vendor` property contains the given match string. Matching is done case-insensitive.

build.gradle

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(11)
            vendor = JvmVendorSpec.matching("customString")
        }
    }

build.gradle.kts

    java {
        toolchain {
            languageVersion.set(JavaLanguageVersion.of(11))
            vendor.set(JvmVendorSpec.matching("customString"))
        }
    }

### Selecting toolchains by their virtual machine implementation

If your project requires a specific implementation, you can filter based on the implementation as well. Currently available implementations to choose from are:

`VENDOR_SPECIFIC`

  Acts as a placeholder and matches any implementation from any vendor (e.g. hotspot, zulu, …​)

`J9`

  Matches only virtual machine implementations using the OpenJ9/IBM J9 runtime engine.

For example, to use an Open J9 JVM, distributed via AdoptOpenJDK, you can specify the filter as shown in the example below.

build.gradle

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(11)
            vendor = JvmVendorSpec.ADOPTOPENJDK
            implementation = JvmImplementation.J9
        }
    }

build.gradle.kts

    java {
        toolchain {
            languageVersion.set(JavaLanguageVersion.of(11))
            vendor.set(JvmVendorSpec.ADOPTOPENJDK)
            implementation.set(JvmImplementation.J9)
        }
    }

| The Java major version, the vendor (if specified) and implementation (if specified) will be tracked as an input for compilation and test execution.

## Specify custom toolchains for individual tasks

In case you want to tweak which toolchain is used for a specific task, you can specify the exact tool a task is using. For example, the `Test` task exposes a `JavaLauncher` property that defines which java executable to use for launching the tests.

In the example below, we configure all java compilation tasks to use JDK8. Additionally, we introduce a new `Test` task that is going to run our unit tests but using a JDK 14.

list/build.gradle

    tasks.withType(JavaCompile).configureEach {
        javaCompiler = javaToolchains.compilerFor {
            languageVersion = JavaLanguageVersion.of(8)
        }
    }
    task('testsOn14', type: Test) {
        javaLauncher = javaToolchains.launcherFor {
            languageVersion = JavaLanguageVersion.of(14)
        }
    }

list/build.gradle.kts

    tasks.withType<JavaCompile>().configureEach {
        javaCompiler.set(javaToolchains.compilerFor {
            languageVersion.set(JavaLanguageVersion.of(8))
        })
    }

    tasks.register<Test>("testsOn14") {
        javaLauncher.set(javaToolchains.launcherFor {
            languageVersion.set(JavaLanguageVersion.of(14))
        })
    }

In addition, in the `application` subproject, we add another Java execution task to run our application with JDK 14.

application/build.gradle

    task('runOn14', type: JavaExec) {
        javaLauncher = javaToolchains.launcherFor {
            languageVersion = JavaLanguageVersion.of(14)
        }

        classpath = sourceSets.main.runtimeClasspath
        mainClass = application.mainClass
    }

application/build.gradle.kts

    tasks.register<JavaExec>("runOn14") {
        javaLauncher.set(javaToolchains.launcherFor {
            languageVersion.set(JavaLanguageVersion.of(14))
        })

        classpath = sourceSets["main"].runtimeClasspath
        mainClass.set(application.mainClass)
    }

Depending on the task, a JRE might be enough while for other tasks (e.g. compilation), a JDK is required. By default, Gradle prefers installed JDKs over JREs if they can satisfy the requirements.

Toolchains tool providers can be obtained from the `javaToolchains` extension.

Three tools are available:

- A `JavaCompiler` which is the tool used by the JavaCompile task

- A `JavaLauncher` which is the tool used by the JavaExec or Test tasks

- A `JavadocTool` which is the tool used by the Javadoc task

### Integration with tasks relying on a Java executable or Java home

Any tasks that can be configured with a path to a Java executable, or a Java home location, can benefit from toolchains.

While you will not be able to wire a toolchain tool directly, they all have metadata that gives access to their full path or to the path of the Java installation they belong to.

For example, you can configure the executable for a Kotlin compile tasks as follows:

build.gradle

    def compiler = javaToolchains.compilerFor {
        languageVersion = JavaLanguageVersion.of(11)
    }

    tasks.withType(KotlinJvmCompile).configureEach {
        kotlinOptions.jdkHome = compiler.get().metadata.installationPath.asFile.absolutePath
    }

build.gradle.kts

    val compiler = javaToolchains.compilerFor {
        languageVersion.set(JavaLanguageVersion.of(11))
    }

    tasks.withType<KotlinJvmCompile>().configureEach {
        kotlinOptions.jdkHome = compiler.get().metadata.installationPath.asFile.absolutePath
    }

Similarly, doing `compiler.get().executablePath` would give you the full path to `javac` for the given toolchain. Please note however that this may realize (and provision) a toolchain eagerly.

## Auto detection of installed toolchains

By default, Gradle automatically detects local JRE/JDK installations so no further configuration is required by the user. The following is a list of common package managers and locations that are supported by the JVM auto detection.

Operation-system specific locations:

- Linux

- MacOs

- Windows

Supported Package Managers:

- Asdf-vm

- Jabba

- SDKMAN!

### How to disable auto-detection

In order to disable auto-detection, you can use the `org.gradle.java.installations.auto-detect` Gradle property:

- Either start gradle using `-Porg.gradle.java.installations.auto-detect=false`

- Or put `org.gradle.java.installations.auto-detect=false` into your `gradle.properties` file.

## Auto Provisioning

If Gradle can’t find a locally available toolchain which matches the requirements of the build, it will automatically try to download it from AdoptOpenJDK. By default, it will request a HotSpot JDK matching the current operating system and architecture. Provisioning JDKs are installed in the Gradle User Home directory.

| Gradle will only download JDK versions for GA releases. There is no support for downloading early access versions.

By default, the public AdoptOpenJDK APIs are used to determine and download a matching JDK. In case you want to use another server that is compatible with v3 of the AdoptOpenJDK API, you can point Gradle to use a different host. For that you use the Gradle property as in the example below:

    org.gradle.jvm.toolchain.install.adoptopenjdk.baseUri=https://api.company.net/

| Only secure protocols like `https` are accepted. This is required to make sure no one can tamper with the download in flight.

### Viewing and debugging toolchains

Gradle can display the list of all detected toolchains including their metadata.

For example, to show all toolchains of a project, run:

    gradle -q javaToolchains

Output of `gradle -q javaToolchains`

    > gradle -q javaToolchains

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

     + AdoptOpenJDK 1.8.0_242
         | Location:           /Users/username/myJavaInstalls/8.0.242.hs-adpt/jre
         | Language Version:   8
         | Vendor:             AdoptOpenJDK
         | Is JDK:             true
         | Detected by:        system property 'org.gradle.java.installations.paths'

     + OpenJDK 15-ea
         | Location:           /Users/username/.sdkman/candidates/java/15.ea.21-open
         | Language Version:   15
         | Vendor:             AdoptOpenJDK
         | Is JDK:             true
         | Detected by:        SDKMAN!

     + OpenJDK 16
         | Location:           /Users/user/customJdks/16.ea.20-open
         | Language Version:   16
         | Vendor:             AdoptOpenJDK
         | Is JDK:             true
         | Detected by:        environment variable 'JDK16'

     + Oracle JDK 1.7.0_80
         | Location:           /Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home/jre
         | Language Version:   7
         | Vendor:             Oracle
         | Is JDK:             true
         | Detected by:        macOS java_home

This can help to debug which toolchains are available to the build, how they are detected and what kind of metadata Gradle knows about those toolchains.

### How to disable auto provisioning

In order to disable auto-provisioning, you can use the `org.gradle.java.installations.auto-download` Gradle property:

- Either start gradle using `-Porg.gradle.java.installations.auto-download=false`

- Or put `org.gradle.java.installations.auto-download=false` into a `gradle.properties` file.

## Custom Toolchain locations

If auto-detecting local toolchains is not sufficient or disabled, there are additional ways you can let Gradle know about installed toolchains.

If your setup already provides environment variables pointing to installed JVMs, you can also let Gradle know about which environment variables to take into account. Assuming the environment variables `JDK8` and `JRE14` point to valid java installations, the following instructs Gradle to resolve those environment variables and consider those installations when looking for a matching toolchain.

    org.gradle.java.installations.fromEnv=JDK8,JRE14

Additionally, you can provide a comma-separated list of paths to specific installations using the `org.gradle.java.installations.paths` property. For example, using the following in your `gradle.properties` will let Gradle know which directories to look at when detecting JVMs. Gradle will treat these directories as possible installations but will not descend into any nested directories.

    org.gradle.java.installations.paths=/custom/path/jdk1.8,/shared/jre11

## Toolchains for plugin authors

Custom tasks that require a tool from the JDK should expose a `Property<T>` with the desired tool as generic type. The property should be declared as a `@Nested` input. By injecting the `JavaToolchainService` in the plugin or task, it is also possible to wire a convention in those properties by obtaining the `JavaToolchainSpec` from the `java` extension on the project. The example below showcases how to use the default toolchain as convention while allowing users to individually configure the toolchain per task.

build.gradle

    import javax.inject.Inject;

    abstract class CustomTaskUsingToolchains extends DefaultTask {

        @Nested
        abstract Property<JavaLauncher> getLauncher()

        @Inject
        CustomTaskUsingToolchains() {
            // Access the default toolchain
            def toolchain = project.getExtensions().getByType(JavaPluginExtension.class).toolchain

            // acquire a provider that returns the launcher for the toolchain
            JavaToolchainService service = project.getExtensions().getByType(JavaToolchainService.class)
            Provider<JavaLauncher> defaultLauncher = service.launcherFor(toolchain);

            // use it as our default for the property
            launcher.convention(defaultLauncher);
        }

        @TaskAction
        def showConfiguredToolchain() {
            println launcher.get().executablePath
            println launcher.get().metadata.installationPath
        }
    }

    plugins {
        id 'java'
    }

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(8)
        }
    }

    tasks.register('showDefaultToolchain', CustomTaskUsingToolchains)

    tasks.register('showCustomToolchain', CustomTaskUsingToolchains) {
        launcher = javaToolchains.launcherFor {
            languageVersion = JavaLanguageVersion.of(14)
        }
    }

build.gradle.kts

    import javax.inject.Inject;

    abstract class CustomTaskUsingToolchains : DefaultTask {

        @get:Nested
        abstract val launcher: Property<JavaLauncher>

        @Inject
        constructor() {
            // Access the default toolchain
            val toolchain = project.extensions.getByType<JavaPluginExtension>().toolchain

            // acquire a provider that returns the launcher for the toolchain
            val service = project.extensions.getByType<JavaToolchainService>()
            val defaultLauncher = service.launcherFor(toolchain)

            // use it as our default for the property
            launcher.convention(defaultLauncher);
        }

        @TaskAction
        fun showConfiguredToolchain() {
            println(launcher.get().executablePath)
            println(launcher.get().metadata.installationPath)
        }
    }

    plugins {
        java
    }

    java {
        toolchain {
            languageVersion.set(JavaLanguageVersion.of(8))
        }
    }

    tasks.register<CustomTaskUsingToolchains>("showDefaultToolchain")

    tasks.register<CustomTaskUsingToolchains>("showCustomToolchain") {
        launcher.set(javaToolchains.launcherFor {
            languageVersion.set(JavaLanguageVersion.of(14))
        })
    }

| With the property correctly configured as `@Nested`, it will automatically track the Java major version, the vendor (if specified) and implementation (if specified) as an input.