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

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.

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.

Currently, the following built-in Gradle tasks are cacheable:

• Java toolchain:JavaCompile,Javadoc

• Groovy toolchain:GroovyCompile,Groovydoc

• Scala toolchain:ScalaCompile,PlatformScalaCompile,ScalaDoc

• Native toolchain:CppCompile,CCompile,SwiftCompile

• Testing:Test

• Code quality tasks:Checkstyle,CodeNarc,Pmd

• JaCoCo:JacocoMerge,JacocoReport

• Other tasks:AntlrTask,ValidatePlugins,WriteProperties

All other built-in tasks are currently not cacheable.

Some tasks, likeCopy orJar, usually do not make sense to make cacheable because Gradle is only copying files from one location to another.It also doesn’t make sense to make tasks cacheable that do not produce outputs or have no task actions.

There are third party plugins that work well with the build cache.The most prominent examples are theAndroid plugin 3.1+ and theKotlin plugin 1.2.21+.For other third party plugins, check their documentation to find out whether they support the build cache.

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.(Seethe section called "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.

There are certain tasks that don’t benefit from using the build cache.One example is a task that only moves data around the file system, like aCopy task.You can signify that a task is not to be cached by adding the@DisableCachingByDefault annotation to it.You can also give a human-readable reason for not caching the task by default.The annotation can be used on its own, or together with@CacheableTask.

We create a subclass of theNpmTask and useannotations to declare the inputs and outputs.

When possible, it is better to use delegation instead of creating a subclass.That is the case for the built inJavaExec,Exec,Copy andSync tasks, which have a method onProject to do the actual work.

If you’re a modern JavaScript developer, you know that bundling can be quite long, and is worth caching.To achieve that, we need to tell Gradle that it’s allowed to cache the output of that task, using the@CacheableTask annotation.

This is sufficient to make the task cacheable on your own machine.However, input files are identified by default by their absolute path.So if the cache needs to be shared between several developers or machines using different paths, that won’t work as expected.So we also need to set thepath sensitivity.In this case, the relative path of the input files can be used to identify them.

Note that it is possible to override property annotations from the base class by overriding the getter of the base class and annotating that method.

• (1) Add@CacheableTask to enable caching for the task.

• (2) Override the getter of a property of the base class to change the input annotation to@Internal.

• (3) (4) Declare the path sensitivity.

If for some reason you cannot create a new custom task class, it is also possible to make a task cacheable using theruntime API to declare the inputs and outputs.

For enabling caching for the task you need to use theTaskOutputs.cacheIf() method.

The declarations via the runtime API have the same effect as the annotations described above.Note that you cannot override file inputs and outputs via the runtime API.Input properties can be overridden by specifying the same property name.

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 by removing entries that have not been used recently to conserve disk space.

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

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.

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

The recommended use case for the remote build cache is that your continuous integration server populates it from clean builds while developers only load from it.The configuration would then look as follows.

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’scomposite build feature allows including other complete Gradle builds into another.Such included builds will inherit the build cache configuration from the top level build, regardless of whether the included builds define build cache configuration themselves or not.

The build cache configuration present for any included build is effectively ignored, in favour of the top level build’s configuration.This also applies to anybuildSrc projects of any included builds.

ThebuildSrc directory is treated as anincluded build, and as such it inherits the build cache configuration from the top-level build.