Build Cache - Gradle User Guide Version 3.5

# Chapter 15. Build Cache

This feature is a work in progress.

The build cache feature described here is different from the Android plugin build cache.

## 15.1. Overview

The Gradle build cache is a cache mechanism that aims to save time by reusing outputs produced by other builds. The build cache works by storing (locally or remotely) build outputs and allowing builds to fetch these outputs from the cache when it is determined that inputs have not changed, avoiding the expensive work of regenerating them.

A first feature using the build cache is task output caching. Essentially, task output caching leverages the same intelligence as up-to-date checks that Gradle uses to avoid work when a previous local build has already produced a set of task outputs. But instead of being limited to the previous build in the same workspace, task output caching allows Gradle to reuse task outputs from any earlier build in any location on the local machine. When using a shared build cache for task output caching this even works across developer machines and build agents.

Apart from task output caching, we expect other features to use the build cache in the future.

## 15.2. Enable the Build Cache

By default, the build cache is not enabled. You can enable the build cache in a couple of ways:

Run with `--build-cache` on the command-line
  Gradle will use the build cache for this build only.
Put `org.gradle.caching=true` in your `gradle.properties`
  Gradle will try to reuse outputs from previous builds for all builds, unless explicitly disabled with `--no-build-cache`.

When the build cache is enabled, it will store build outputs in the Gradle user home. For configuring this directory or different kinds of build caches see Section 15.4, “Configure the Build Cache”.

## 15.3. Task Output Caching

Beyond incremental builds described in Section 19.10, “Up-to-date checks (AKA Incremental Build)”, Gradle can save time by reusing outputs from previous executions of a task by matching inputs to the task. Task outputs can be reused between builds on one computer or even between builds running on different computers via a build cache.

For an initial release, we have focused on the use case where users have an organization-wide remote build cache that is populated regularly by continuous integration builds. Developers and other continuous integration agents should pull cache entries from the remote build cache. We expect that developers will not be allowed to populate the remote build cache, and all continuous integration builds populate the build cache after running the `clean` task.

For your build to play well with task output caching it must work well with the incremental build feature. For example, when running your build twice in a row all tasks with outputs should be `UP-TO-DATE`. You cannot expect faster builds or correct builds when enabling task output caching when this prerequisite is not met.

This feature is a work in progress and is automatically enabled when you enable the build cache, see Section 15.2, “Enable the Build Cache”.

### 15.3.1. What does it look like

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 compileJava
    Build cache is an incubating feature.
    Using directory (/home/user/.gradle/caches/build-cache-1) as local build cache, push is enabled.
    :compileJava
    :processResources
    :classes
    :jar
    :assemble

    BUILD 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
    :clean

    BUILD SUCCESSFUL

    $> gradle --build-cache assemble
    Build cache is an incubating feature.
    Using directory (/home/user/.gradle/caches/build-cache-1) as local build cache, push is enabled.
    :compileJava FROM-CACHE
    :processResources
    :classes
    :jar
    :assemble

    BUILD 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` being lifecycle tasks and `:processResources` and `:jar` being Copy-like tasks which are not cacheable since it is generally faster to execute them.

### 15.3.2. Task Output Caching in detail

Since a task describes all of its inputs and outputs, Gradle can compute a build 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. your continuous 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 for up-to-date checks:

- The task type and its classpath
- The names of the output properties
- The names and values of properties annotated as described in the section called “Custom task types”
- The names and values of properties added by the DSL via `TaskInputs`
- The classpath of the Gradle distribution, buildSrc and plugins
- The content of the build script when it affects execution of the task

Task types need to opt-in to task output caching using the `@`CacheableTask`` annotation. Note that `@`CacheableTask`` is, like `@`ParallelizableTask``, not inherited by subclasses. Custom task types are not cacheable by default. Currently, the following built-in Gradle tasks are cacheable:

- Java toolchain: `JavaCompile`, `Javadoc`
- Groovy toolchain: `GroovyCompile`, `Groovydoc`
- `Test`
- Code quality tasks: `Checkstyle`, `CodeNarc`, `FindBugs`, `JDepend`, `Pmd`
- Jacoco: `JacocoMerge`, `JacocoReport`
- `ValidateTaskProperties`

### 15.3.3. Declaring task inputs and outputs

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. (See Section 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``).

### 15.3.4. Feedback and known issues

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 on incremental 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 these Github issues.

When reporting issues with the build cache, please check if your issue is a known issue or related to a known issue.

#### Correctness issues

These issues may affect the correctness of your build when using the build cache. Please consider these issues carefully.

Table 15.1. Correctness issues

Description | Impact | Workaround
Stale outputs left behind by older versions of a plugin or Gradle. | Gradle does not automatically clean up outputs from other versions of Gradle. In some cases, changing the version of Gradle or changing the version of a plugin can lead to inconsistent builds. | Use `clean` builds when publishing to a remote build cache.
Mixed source projects with Java and another JVM language. | If a project has both a Java source set and another source set for a different JVM language, the compilation tasks share an output directory. This causes Gradle to mix the result of one task into another. Depending on the order the tasks run, Gradle may delete all output from one of the tasks and cause broken builds. | Only use one compilation task. For example, if you use Java and Groovy, put all Java sources in `src/main/groovy`.
Overlapping outputs. | If two cacheable tasks share an output directory, Gradle does not reliably cache the results from either task. More precisely, Gradle is not able to determine which outputs belong to which task and will possibly store the combined output of both tasks in the build cache. When loading from the build cache you can get the combined output when you expect a single output and vice versa. | Disable caching for both tasks. You can detect this situation by using this init script.
Tracking the Java vendor implementation | Gradle currently tracks the major version of Java that is used for compilation and test execution. If your build uses several Java implementations (IBM, OpenJDK, Oracle, etc) that are the same major version, Gradle will treat them all as equivalent and re-use outputs from any implementation. | Only enable caching for builds that all use the same Java implementation or manually add the Java vendor as an input to compilation and test execution tasks by using the runtime api for adding task inputs.
Tracking the Java version | Gradle currently tracks the major version of Java (6 vs 7 vs 8) that is used for compilation and test execution. If your build expects to use several minor releases (1.8.0_102 vs 1.8.0_25), Gradle will treat all of these as equivalent and re-use outputs from any minor version. In our experience, bytecode produced by each major version is functionally equivalent. | Manually add the full Java version as an input to compilation and test execution tasks by using the runtime api for adding task inputs.
Changes in Gradle’s file encoding that affect the build script | Gradle can produce different task output based on the file encoding used by the JVM. Gradle will use a default file encoding based on the operating system if `file.encoding` is not explicitly set. | Set the UTF-8 file encoding on all tasks which allow setting the encoding. Use UTF-8 file encoding everywhere by setting `file.encoding` to `UTF-8` for the Gradle JVM.
Javadoc ignores custom command-line options | Gradle’s Javadoc task does not take into account any changes to custom command-line options. | You can add your custom options as input properties or disable caching of Javadoc.

#### Caveats

These issues may affect the number of cache hits you get between machines.

Table 15.2. Caveats

Description | Impact | Workaround
Line endings in build scripts files. | Gradle calculates the build cache key based on the MD5 hash of the build script contents. If the line endings are different between developers and the CI servers, Gradle will calculate different build cache keys even when all other inputs to a task are the same. | Check if your VCS will change source file line endings and configure it to have a consistent line ending across all platforms.
Absolute paths in command-line arguments and system properties. | Gradle provides ways of specifying the path sensitivity for individual task properties (see `@`PathSensitive``); however, it is common to need to pass absolute paths to tools or to tests via system properties or command line arguments. These kinds of inputs will cause cache misses because not every developer or CI server uses an identical absolute path to the root of a build. | None.
Using JaCoCo disables caching of the Test task. | The JaCoCo agent relies on appending to a shared output file that may be left over from a different test execution. If Gradle allowed Test tasks to be cacheable with the JaCoCo plugin, it could not guarantee the same results each time. | None.
Adding new actions to cacheable tasks in a build file makes that task sensitive to unrelated changes to the build file. | Actions added by a plugin (from buildSrc or externally) do not have this problem because their classloader is restricted to the classpath of the plugin. | Avoid adding actions to cacheable tasks in a build file.
Modifying inputs or outputs during task execution. | It’s possible to modify a task’s inputs or outputs during execution in ways that change the output of a task. This breaks incremental builds and can cause problems with the build cache. | Use a configure task to finalize configuration for a given task. A configure task configures another task as part of its execution.
Files with volatile data. | If input files for a cacheable task change on every build, such as when they contain a timestamp, the task is unlikely to have very many build cache hits. If these files are contained in jars, it can affect the cacheability of Java compilation and test execution. Java compilation is only affected when the jar is found on the annotation processor classpath due to compile avoidance. | You can produce consistently ordered properties files without a timestamp comment with `WriteProperties`.
Order of input files affects outputs. | Some tools are sensitive to the order of its inputs and will produce slightly different output. Gradle will usually provide the order of files from the filesystem, which will be different across operating systems. | Provide a stable order for tools affected by order.
ANTLR3 produces output with a timestamp. | When generating Java source code with ANTLR3 and the Chapter 58, The ANTLR Plugin, the generated sources contain a timestamp that reduces how often Java compilation will be cached. ANTLR2 and ANTLR4 are not affected. | If you cannot upgrade to ANLTR4 use a custom template or remove the timestamp in a `doLast` action.

## 15.4. Configure the Build Cache

You can configure the build cache by using the `Settings.buildCache(org.gradle.api.Action)` block in `settings.gradle`.

Gradle supports a `local` and a `remote` build cache that can be configured separately. When both build caches are enabled, Gradle tries to load build outputs from the local build cache first and then tries the remote build cache if no build outputs are found. Gradle pushes build outputs to any build cache that is enabled and has `BuildCache.isPush()` set to `true`.

By default, the local build cache has push enabled, and the remote build cache has push disabled.

The local build cache is pre-configured to be a `DirectoryBuildCache` and enabled by default. The remote build cache can be configured by specifying the type of build cache to connect to (`BuildCacheConfiguration.remote(java.lang.Class)`).

Gradle supports connecting to a remote build cache backend via HTTP. This can be configured in `settings.gradle`. For more details on what the protocol looks like see `HttpBuildCache`. 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.

Example 15.1. Pull from HttpBuildCache

`settings.gradle`

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

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

Example 15.2. Recommended setup for CI push use case

`settings.gradle`

    ext.isCiServer = System.getenv().containsKey("CI")

    buildCache {
        local {
            enabled = !isCiServer
        }
        remote(HttpBuildCache) {
            url = 'https://example.com:8123/build-cache/'
            push = isCiServer
        }
    }

If you use a `buildSrc` 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 to `buildSrc/settings.gradle` and `settings.gradle` as shown in the following example.

Example 15.3. Consistent setup for buildSrc and main build

`settings.gradle`

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

`buildSrc/settings.gradle`

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

`gradle/buildCacheSettings.gradle`

    ext.isCiServer = System.getenv().containsKey("CI")

    buildCache {
        local {
            enabled = !isCiServer
        }
        remote(HttpBuildCache) {
            url = 'https://example.com:8123/build-cache/'
            push = isCiServer
        }
    }

You can configure the directory the `DirectoryBuildCache` uses to store the build outputs and the credentials the `HttpBuildCache` uses to access the build cache server as shown in the following example.

Example 15.4. Configure built-in build caches

`settings.gradle`

    buildCache {
        local(DirectoryBuildCache) {
            directory = new File(rootDir, 'build-cache')
        }
        remote(HttpBuildCache) {
            url = 'http://example.com:8123/build-cache/'
            credentials {
                username = 'build-cache-user'
                password = 'some-complicated-password'
            }
        }
    }

## 15.5. How to set up an HTTP build cache backend

It is possible to configure nginx to act as an HTTP build cache backend. Instructions on how to do so can be found here.

## 15.6. Implement your own Build Cache

Using a different build cache backend to store build outputs (which is not covered by the built-in support for connecting to an HTTP backend) requires implementing your own logic for connecting to your custom build cache backend. To this end, custom build cache types can be registered via `BuildCacheConfiguration.registerBuildCacheService(java.lang.Class, java.lang.Class)`. For an example of what this could look like see the Gradle Hazelcast plugin.

## 15.7. Known issues with built-in Build Caches

The built-in build caches have some known issues which will be addressed in future releases.

Table 15.3. `DirectoryBuildCache`

Description | Impact | Workaround
No limit on the size of the directory build cache. | Currently, the directory the build cache uses can grow unbounded. | Periodically delete the directory of the build cache if it grows too large. The default directory for storing build outputs is `caches/build-cache-1` in the Gradle user home. For automatic cleanup tools like tmpreaper can be used.

Table 15.4. `HttpBuildCache`

Description | Impact | Workaround
`--offline` is not honored for the remote build cache. | The built-in HTTP build cache ignores the offline flag. | To completely disable task output caching, use `--no-build-cache`.
Slow/hanging builds when on a poor connection with the remote build cache enabled. | For every cacheable task, Gradle will attempt to find a corresponding cache entry in the remote cache. For large cache entries, it may be slower to download the previous result than to recreate it. | Disable the build cache temporarily with `--no-build-cache`.
No HTTP timeouts. | Gradle does not enforce any HTTP timeout when downloading a cache entry. On a remote build cache that fails to respond, Gradle will wait indefinitely. | None.
Remote cache entries are downloaded each time they are needed. | Gradle does not keep a local copy of remotely downloaded cache entries. After every clean build, Gradle will need to download all remote cache entries again. | None.
Some types of errors when reading or writing to the build cache are considered fatal. | When Gradle fails to store something into the build cache or fails to retrieve something from the build cache, the build may fail. | None.