A complete guide is available aboutusing the build cache. It covers the different scenarios caching can improve, and detailed discussions of the different caveats you need to be aware of when enabling caching for a build.

Run with--build-cache on the command-line

Gradle will use the build cache for this build only.

Putorg.gradle.caching=true in yourgradle.properties

Gradle will try to reuse outputs from previous builds for all builds, unless explicitly disabled with--no-build-cache.

Let us start with a project using the Java plugin which has a few Java source files. We run the build the first time.

$> gradle --build-cache compileJavaBuild cache is an incubating feature.Using local directory build cache for the root build (location = /home/user/.gradle/caches/build-cache-1).:compileJava:processResources:classes:jar:assembleBUILD SUCCESSFUL

We see the directory used by the local build cache in the output. Apart from that the build was the same as without the build cache.Let’s clean and run the build again.

$> gradle clean:cleanBUILD SUCCESSFUL

$> gradle --build-cache assembleBuild cache is an incubating feature.Using local directory build cache for the root build (location = /home/user/.gradle/caches/build-cache-1).:compileJava FROM-CACHE:processResources:classes:jar:assembleBUILD SUCCESSFUL

Now we see that, instead of executing the:compileJava task, the outputs of the task have been loaded from the build cache.The other tasks have not been loaded from the build cache since they are not cacheable. This is due to:classes and:assemble beinglifecycle tasks and:processResourcesand:jar being Copy-like tasks which are not cacheable since it is generally faster to execute them.

Since a task describes all of its inputs and outputs, Gradle can compute abuild cache key that uniquely defines the task’s outputs based on its inputs.That build cache key is used to request previous outputs from a build cache or push new outputs to the build cache. If the previous build is already populated by someone else, e.g. yourcontinuous integration server or other developers, you can avoid executing most tasks locally.

The following inputs contribute to the build cache key for a task in the same way that they do forup-to-date checks:

Task types need to opt-in to task output caching using the@CacheableTask annotation.Note that@CacheableTask is not inherited by subclasses.Custom task types arenot cacheable by default.

It is very important that a cacheable task has a complete picture of its inputs and outputs, so that the results from one build can be safely re-used somewhere else.

Missing task inputs can cause incorrect cache hits, where different results are treated as identical because the same cache key is used by both executions.Missing task outputs can cause build failures if Gradle does not completely capture all outputs for a given task.Wrongly declared task inputs can lead to cache misses especially when containing volatile data or absolute paths.(SeeSection 19.10.1, “Task inputs and outputs” on what should be declared as inputs and outputs.)

In order to ensure that the inputs and outputs are properly declared use integration tests (for example using TestKit) to check that a task produces the same outputs for identical inputs and captures all output files for the task.We suggest adding tests to ensure that the task inputs are relocatable, i.e. that the task can be loaded from the cache into a different build directory (see@PathSensitive).

In order to handle volatile inputs for your tasks considerconfiguring input normalization.

The task output caching feature has known issues that may impact the correctness of your build when using the build cache,and there are some caveats to keep in mind which may reduce the number of cache hits you get between machines.These issues will be corrected as this feature becomes stable.

Note that task output caching relies onincremental build.Problems that affect incremental builds can also affect task output caching even if the affected tasks are not cacheable.Most issues only cause problems if your build cache is populated by non-clean builds or if caching has been enabled for unsupported tasks.For a current list of open problems with incremental builds see theseGithub issues.

The built-in local build cache,DirectoryBuildCache, uses a directory to store build cache artifacts.By default, this directory resides in the Gradle user home directory, but its location is configurable.

Gradle will periodically clean-up the local cache directory to reduce it to a configurable target size.This means that the local build cache directory may temporarily grow over the target size until the next clean-up is scheduled.

For more details on the configuration options refer to the DSL documentation ofDirectoryBuildCache.Here is an example of the configuration.

buildCache {    local(DirectoryBuildCache) {        directory =new File(rootDir,'build-cache')        targetSizeInMB =1024    }}

Gradle has built-in support for connecting to a remote build cache backend via HTTP.For more details on what the protocol looks like seeHttpBuildCache.Note that by using the following configuration the local build cache will be used for storing build outputs while the local and the remote build cache will be used for retrieving build outputs.

buildCache {    remote(HttpBuildCache) {        url ='https://example.com:8123/cache/'    }}

You can configure the credentials theHttpBuildCache uses to access the build cache server as shown in the following example.

buildCache {    remote(HttpBuildCache) {        url ='http://example.com:8123/cache/'        credentials {            username ='build-cache-user'            password ='some-complicated-password'        }    }}

buildCache {    remote(HttpBuildCache) {        url ='https://example.com:8123/cache/'        allowUntrustedServer = true    }}

The recommended use case for the build cache is that your continuous integration server populates the remote build cache with clean builds while developers pullfrom the remote build cache and push to a local build cache. The configuration would then look as follows.

ext.isCiServer = System.getenv().containsKey("CI")buildCache {    local {        enabled = !isCiServer    }    remote(HttpBuildCache) {        url ='https://example.com:8123/cache/'        push = isCiServer    }}

If you use abuildSrc directory, you should make sure that it uses the same build cache configuration as the main build.This can be achieved by applying the same script tobuildSrc/settings.gradle andsettings.gradle as shown in the following example.

apply from:new File(settingsDir,'gradle/buildCacheSettings.gradle')

apply from:new File(settingsDir,'../gradle/buildCacheSettings.gradle')

ext.isCiServer = System.getenv().containsKey("CI")buildCache {    local {        enabled = !isCiServer    }    remote(HttpBuildCache) {        url ='https://example.com:8123/cache/'        push = isCiServer    }}

It is also possible to configure the build cache from aninit script, which can be used from the command line, added to your Gradle user home or be a part of your custom Gradle distribution.

gradle.settingsEvaluated { settings ->    settings.buildCache {// vvv Your custom configuration goes here        remote(HttpBuildCache) {            url ='https://example.com:8123/cache/'        }// ^^^ Your custom configuration goes here    }}