Gradle Build Cache Basics

1. Overview

Build caches can make the code build process faster and, thus, improve developers’ productivity. In this article, we’ll learn about the basics of Gradle build cache.

2. What Is Gradle Build Cache?

The Gradle build cache is semi-permanent storage that saves the build tasks’ outputs. It enables the reuse of already generated artifacts from the previous builds. The guiding principle behind the Gradle build cache is that it should avoid rebuilding the tasks that have already been built, provided the inputs are not changed. In this way, the time to complete the subsequent builds is reduced.

In Gradle, a build cache key uniquely identifies an artifact or a task output. Before executing a task, Gradle computes the cache key by hashing each input to the task. It then looks at the remote or local cache to check if the task output corresponding to the computed cache key already exists. If it’s not present, then the task is executed. Otherwise, Gradle reuses the existing task output.

Now, let’s look at two different kinds of Gradle build caches.

2.1. Local Build Cache

The local build cache uses a system directory to store tasks outputs. The default location is the Gradle user home directory that points to $USER_HOME/.gradle/caches. Every time we run the build in our system, artifacts will be stored here. It is enabled by default, and its location is configurable.

2.2. Remote Build Cache

The remote cache is a shared build cache. Reading from and writing to the remote cache is done via HTTP. One of the most common use cases of remote cache is continuous integration builds. On every clean build, the CI server populates the remote cache. So, the components that are changed will not be rebuilt, thereby speeding up the CI builds. Moreover, task outputs can also be shared among CI agents. The remote cache is not enabled by default.

When both remote and local caches are enabled, then the build output is first checked in the local cache. If the output isn’t present in the local cache, it’ll be downloaded from the remote cache and also stored in the local cache. Then, in the next build, the same task output is taken from the local cache to speed up the build process.

3. Configuring Gradle Build Cache

We can configure the caches by providing the Settings.build-cache block in the settings.gradle file. Here, we’re using Groovy closures for writing configurations. Let’s look at how to configure different types of cache.

3.1. Configuring Local Build Cache

Let’s add the local build cache configuration in the settings.gradle file:

buildCache {
    local {
        directory = new File(rootDir, 'build-cache')
        removeUnusedEntriesAfterDays = 30
    }
}

In the above code block, the directory object represents the location to store the build outputs. Here, the rootDir variable represents the root directory of the project. We can also change the directory object to point to another location.

To save space, the local build cache also removes the entries periodically that are not being used for a specified period of time. The property removeUnusedEntriesAfterDays is used to configure the number of days after which unused artifacts will be removed from the local cache. Its default value is seven days.

We can also clean it manually by deleting the entries from the $USER_HOME/.gradle/caches folder. On a Linux system, we can use the rm command to clean the directory:

rm -r $HOME/.gradle/caches

We can also configure some additional properties. For instance, enabled is a boolean property that represents whether the local cache is enabled or not. Build outputs will be stored in the cache if the push property is set to true. Its value is true for the local build cache by default.

3.2. Configuring Remote Cache

Let’s add the buildCache block in settings.gradle file to configure the remote cache.

For remote cache, we need to provide the location in the form of URL as well as the username and password to access it:

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

4. Advantages of Using Gradle Build Cache

Now let’s look at some of the benefits of using Gradle build cache:

• It can improve the productivity of a developer by reducing the build time.
• Because task outputs are reused if the inputs are not changed, it can also help in reducing the build time when switching back and forth between version control branches.
• Using remote cache can significantly reduce the amount of work CI agents need to do to generate the builds. This also reduces the infrastructure needed for the CI builds.
• Reduces the network usage on the CI machines, as results from the remote cache will be stored in the local cache.
• The remote cache can help in sharing the results among developers. This eliminates the need to re-build the changes locally made by other developers working on the same project.
• The remote cache can also enable sharing of the builds among CI agents.
• As build time is reduced, this leads to faster feedback cycles. Hence, builds will be generated more often. Consequently, this could improve the quality of the software.

5. Conclusion

In this article, we learned about Gradle build cache and how it speeds up the build process. We also explored its different types and their configuration. Finally, we discussed the benefits of Gradle build cache.