skip to content

A legacy build uses sourceCompatibility/targetCompatibility and org.gradle.java.home to pin its JDK. How would you migrate it to a declared toolchain, and what behaviour changes should you expect?

level: seniorimportance: should knowfreq 35%

answer

  1. drop org.gradle.java.home + source/target
  2. add java { toolchain { languageVersion } }
  3. Gradle JVM now unpinned
  4. fail-fast if JDK missing
  5. cross-compile => options.release

basics

~20 s

Replace org.gradle.java.home + sourceCompatibility/targetCompatibility with a java { toolchain { languageVersion = ... } } block. Now Gradle, not the developer's environment, selects the compile JDK, and the Gradle daemon can run on a different JDK.

solid answer

~50 s

The legacy pattern ties the build to the environment: `org.gradle.java.home` forces the whole Gradle process onto one JDK, and `sourceCompatibility`/`targetCompatibility` only set bytecode levels. Migration: ```kotlin java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } ``` and **remove** `org.gradle.java.home` plus the `sourceCompatibility`/`targetCompatibility` lines (the toolchain infers the bytecode level). Behaviour changes to expect: - The **Gradle daemon** is no longer pinned — it can run on a newer/different JDK than the compile JDK. - Gradle now **locates** the JDK 17 installation itself (local detection, or provisioning if enabled); if it's missing the build fails fast instead of silently using whatever ran Gradle. - If you still need to cross-compile to a lower bytecode while building on a newer JDK, add `options.release`. Validate with `./gradlew -q javaToolchains` to confirm which JDK resolves. This makes the build reproducible across machines rather than dependent on each developer's `JAVA_HOME`.

code

kotlin · 9 lines
kotlin
// Before: gradle.properties had org.gradle.java.home=/path/to/jdk17
//         build had sourceCompatibility/targetCompatibility = 17

// After:
java {
    toolchain { languageVersion = JavaLanguageVersion.of(17) }
}
// If you must build on a newer JDK but ship 17 bytecode, add:
// tasks.withType<JavaCompile>().configureEach { options.release = 17 }

go deeper

for a junior

Know the replacement: a java { toolchain { } } block instead of the old properties.

for a middle

List what to remove and that Gradle now selects the JDK and can fail fast if it's missing.

for a senior

Handle the cross-compile nuance (options.release), the unpinned Gradle JVM, and CI provisioning implications.

for a principal

Drive the migration org-wide via a convention plugin, standardising toolchains and ensuring agent images or provisioning satisfy the fail-fast resolution.

## The legacy setup and its problems A pre-toolchain build typically has, in `gradle.properties`: ``` org.gradle.java.home=/usr/lib/jvm/jdk-17 ``` and in the build script: ```kotlin java { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } ``` Problems: - `org.gradle.java.home` pins the **entire Gradle process** (daemon + compile) to one absolute path — non-portable across machines/CI. - `source/targetCompatibility` only sets bytecode levels; it doesn't guarantee *which* JDK compiles, so behaviour still depends on whatever JDK the path points to. - Upgrading Gradle (which may need a newer Gradle JVM) conflicts with the pinned compile JDK. ## Target setup ```kotlin java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } ``` Then delete `org.gradle.java.home` and the `source/targetCompatibility` lines. ## Behaviour changes to expect 1. **Gradle JVM is unpinned.** The daemon now uses the ambient `JAVA_HOME`/PATH (subject to Gradle's minimum JDK), which can differ from the toolchain. This is usually desirable — you can run Gradle on JDK 21 while compiling to JDK 17. 2. **Gradle selects the compile JDK.** It scans detected installations for a matching JDK 17. If none is found and auto-provisioning is enabled, it can download one; otherwise the build **fails fast** with a clear 'no compatible toolchain' error — a behaviour change from the old silent fallback. 3. **Bytecode level is inferred** from the toolchain language version, so dropping `source/targetCompatibility` is safe *unless* you were cross-compiling. If you were building on a newer JDK but emitting older bytecode, preserve that with `options.release = N` rather than re-adding source/target. 4. **Portability/reproducibility improves**: no absolute paths in `gradle.properties`; the build declares the JDK it needs and the same script works on every machine. ## Migration checklist ```text [ ] Add java { toolchain { languageVersion = JavaLanguageVersion.of(N) } } [ ] Remove org.gradle.java.home from gradle.properties [ ] Remove sourceCompatibility / targetCompatibility (unless cross-compiling) [ ] If cross-compiling, add options.release = <lower N> [ ] Run ./gradlew -q javaToolchains to verify resolution [ ] Ensure CI agents have (or can provision) the requested JDK ``` ## CI considerations Because Gradle now resolves the JDK, CI agents must either ship the required JDK or have auto-provisioning configured. A common rollout is: standardise the toolchain in a convention plugin, then ensure every agent image includes that JDK (or enable provisioning) so the fail-fast behaviour never blocks pipelines unexpectedly. ## Why senior-level The nuance is recognising that removing `source/targetCompatibility` is safe only when you were compiling-and-targeting the *same* version; if you were cross-compiling, the correct replacement is `options.release`, not re-adding the legacy properties. And anticipating the fail-fast change in CI is the architectural insight.

  • After migrating, why might CI start failing where developers' machines pass?
    Gradle now resolves the toolchain JDK itself and fails fast if it's absent. A CI agent without JDK 17 installed (and no provisioning configured) will fail, even though a developer who has it locally succeeds.
  • When is it NOT safe to simply delete sourceCompatibility/targetCompatibility?
    When you were cross-compiling — building on a newer JDK but emitting older bytecode. The toolchain would then default to the newer bytecode level; preserve the lower target with options.release instead.

saying these in an interview costs you the question

  • Keeping org.gradle.java.home alongside a toolchain (it pins the Gradle JVM unnecessarily).
  • Assuming the build still silently falls back to the old JDK if the toolchain isn't found.
  • Re-adding source/target instead of using options.release for cross-compilation.

context

resolving links…