Gradle

What the Wrapper Actually Pins

gradle/wrapper/gradle-wrapper.properties holds a distributionUrl, and the gradlew script downloads and unpacks that distribution into the user home on first use. Committing the wrapper is what makes ./gradlew mean the same thing on every machine; invoking a system-installed gradle instead quietly opts out of it.

The wrapper pins Gradle and nothing else. Upgrading Gradle itself is rarely the hard part. What sets the pace is plugins: one compiled against a removed API fails during configuration, and until it publishes a compatible release the options are to stay on the old Gradle version or stop using the plugin. The two Java versions in play are independent of the wrapper and of each other:

• The JDK that runs Gradle itself. Recent major versions have raised that floor, most recently to Java 17 for Gradle 9.
• The JDK your code is compiled and tested with, declared by the Java toolchain, which does not have to be the one running Gradle.

What the Configuration Cache Demands

The configuration cache serializes the task graph once configuration has run and replays it on later builds when nothing that fed configuration changed. That last part trips people up. Reading an environment variable, a system property, or a file during configuration registers that value as a cache input, so a script that consults the clock or a mutable variable misses every time and never says so out loud.

It also enforces rules that older build logic breaks: a task action cannot reach back to the Project object at execution time, cannot capture a Task instance in a closure, and cannot hold state that will not serialize. Providers and value sources are the supported way to read outside state, because they declare the dependency instead of hiding it. Three practical points before you switch it on:

• The problems report is written under build/reports/configuration-cache and groups failures by task, naming the field and type that could not be stored along with the script or plugin that introduced it.
• A task that cannot be fixed yet can be marked with notCompatibleWithConfigurationCache and a reason, so the rest of the build still gets the cache instead of the whole feature being turned off.
• The configuration cache and the build cache solve different problems. One skips configuration, the other skips task execution, and enabling either does nothing for the other.

Cache Hits You Are Not Getting

A cacheable task produces an entry keyed by a hash of everything declared: input files, input properties, the task's own classpath, and its implementation class. Change any one and the key changes. When a task you expected to come back from cache runs anyway, org.gradle.caching.debug=true prints the individual hashes that went into the key, and comparing that output across two builds names the input that moved instead of leaving you to guess.

The causes are mundane and mostly fixable: an absolute path captured in an input property, a timestamp written into a manifest, an annotation processor that is not itself cacheable. Some tasks, though, can never produce an entry at all:

• Tasks with no declared outputs. There is nothing to store, so there is nothing to restore.
• Tasks whose output directory overlaps another task's. Gradle disables caching for both, because it cannot tell which task owns which file.
• Tasks not marked cacheable. @CacheableTask is opt-in, and a custom task without it re-executes even when everything around it hits.
• Tasks with an input that changes on every run: a build number, a commit hash, a timestamp. The key is different by construction.

Reading the Dependency Graph

Gradle resolves a version conflict by selecting the highest version present in the graph. Maven picks the nearest declaration to the root instead, so a module that behaved one way under Maven can land on a different version under Gradle with no dependency declaration changed by anyone.

dependencies prints the resolved graph; dependencyInsight explains why one module ended up on the version it did, including which constraint, platform, or transitive path forced it. Both work per configuration, and compileClasspath and runtimeClasspath routinely resolve differently, so ask the one that matches your question. Two habits are worth the effort:

• Write the resolved graph to a file and diff it between commits. A version change nobody made is usually a transitive upgrade arriving through a version range or a platform bump.
• Treat api and implementation as a technical choice, not a stylistic one. An api dependency lands on the consumer's compile classpath, so an api declaration deep in the module graph widens what every downstream module sees and what has to recompile when it changes.

One Build, Several JVMs

A Gradle build does not run in one JVM. The daemon is one process, test workers are separate processes, and Kotlin compilation runs in a daemon of its own. Each is sized independently, and pressure in one is invisible from the others: an OutOfMemoryError in a test worker tells you nothing about how the daemon is configured.

Daemons persist between builds and idle out after three hours by default. A daemon started under the old settings keeps serving until something invalidates it, which is why a memory change sometimes appears to do nothing at all. --status lists the daemons currently running and their state, and --stop ends them. The three settings that matter sit in three different places:

• Daemon: org.gradle.jvmargs in gradle.properties. Changing it starts a new daemon rather than resizing the running one, so the previous process lingers until it idles out.
• Test workers: maxHeapSize on the Test task, multiplied by maxParallelForks. Four forks at 2 GB each is 8 GB of test processes running alongside the daemon, not instead of it.
• Kotlin compilation: kotlin.daemon.jvmargs, separate again. kapt is the memory-hungry part, since it generates Java stubs for annotation processors to read; KSP reads Kotlin declarations directly and skips that step.