The Gradle Configuration Cache (né Instant Execution) documentation moved to

Project Isolation

Project Isolation is an experimental feature that extends the configuration cache to further improve Gradle performance, in particular the performance of Android Studio and IDEA sync.

In the experiment, the configuration model of Gradle projects are "isolated" from each other. This means that build logic, such as build scripts or plugins, applied to a project cannot directly access the configuration of another project. This will allow configuration and tooling model creation for each project to safely run in parallel and the result cached and invalidated for each project independently (the experiment does not do this yet).

The experiment applies some caching to the tooling API operations invoked during Android Studio and IDEA sync. The result of an operation is persisted and reused for later syncs when nothing that affects the IDE model has changed. Generally, the build scripts for the build affect the IDE model, but the source code of the projects does not.

Currently, the caching is coarse-grained and applied to the build as a whole, so that if any build script changes, then the entire cached result is discarded and the entire sync is executed again. Later work will improve the experiment to apply caching at the project level.

How do I use it?

To use project isolation, you will need Gradle 7.1 or later and preferably a recent nightly.

The feature is off by default. You can enable it by setting the org.gradle.unsafe.isolated-projects system property to true. For example:

$ gradle build -Dorg.gradle.unsafe.isolated-projects=true

When enabled, Gradle will fail the build whenever build logic attempts to cross project boundaries and access the model of another project. Gradle collects all of these access problems in the configuration cache report, in the same way as other problems.

The configuration cache command-line options can be used to control how Gradle handles these problems. For example:

  • --configuration-cache-problems=warn can be used to treat the access problems as warnings instead of errors.

  • -Dorg.gradle.unsafe.configuration-cache.max-problems=x can be used to increase the maximum number of problems.

Constraints for build scripts and plugins

Currently, the experiment applies some constraints that prevent build scripts and plugins applied to a project from accessing the state of another project, so that projects can be configured in parallel or not configured at all.

You should note that these constraints are not complete and more will be added over time. Also, it is likely that certain APIs are missing that are necessary for plugin authors to solve their use cases in a way that does not require direct access between projects. An important goal of this experiment is to identify these missing APIs.

At this stage, we do not recommend that you change your plugin to be somehow "project isolation compatible", as there is no stable definition of what this means yet, nor are all the necessary APIs in place to allow this. For now our aim is simply to understand that problems that are caused by adding the isolation. As the experiment continues and we refine the constraints and add new APIs, this will change and we will start encouraging plugin authors to try the new APIs.

The specific constraint that is applied is: build logic applied to a project cannot call any method on a Project instance other than the target of the build logic.

For example, the following will fail because it calls the apply() method on the Project instance of each project in the build:

allprojects {
    // delegate is a Project instance
    apply plugin: 'some-plugin'

However, the following is fine, as it does not call any methods on the Project instance and simply passes it to the method that adds a dependency on the project:

dependencies {
    implementation project(':some-project')