Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Performance and Migration

Gradle Incremental Builds, Up-to-date Checks and Build Cache

Understand how Gradle skips work: task inputs and outputs, up-to-date checks, @Input annotations, the local and remote build cache, cacheability and diagnosing cache misses.

The fastest build step is the one that does not run. Gradle is designed around this idea: each task declares what it reads (inputs) and what it writes (outputs). If the inputs and outputs are the same as in the last run, Gradle prints UP-TO-DATE and does nothing. If the same inputs were seen on another machine or branch, Gradle can even copy the output from a cache.

This lesson explains how those checks work, how to declare inputs and outputs in your own tasks, how the build cache differs from up-to-date checks, and how to find out why a task ran when you expected it not to. It prepares for daemon, parallelism and the configuration cache.

Gradle cannot run on this site; build code is read-only. The Java stand-ins hash inputs the same way and run on Piston.

Up-to-date checks

Before running a task, Gradle computes a fingerprint of:

  • the task's input properties (strings, numbers, flags),
  • the content of its input files,
  • the task's own implementation (class and classpath),
  • the existing output files.

If all of these match the previous execution's record, the task is skipped:

TEXT
> Task :compileJava UP-TO-DATE
> Task :processResources NO-SOURCE
> Task :jar UP-TO-DATE

Status labels you will see:

Label Meaning
(nothing) the task executed
UP-TO-DATE inputs and outputs unchanged, skipped
FROM-CACHE output restored from the build cache
SKIPPED excluded (-x) or onlyIf was false
NO-SOURCE task had no input files to process

Gradle compares content hashes, not timestamps. Touching a file without changing it does not trigger a rebuild, and moving a project to a different directory can still reuse results when paths are declared relatively.

Declaring inputs and outputs

All built-in tasks already do this. For your own tasks, declare them with annotations (in plugin classes) or the inputs and outputs DSL (in scripts):

Kotlin
abstract class Report : DefaultTask() {
    @get:InputFile
    @get:PathSensitive(PathSensitivity.NONE)
    abstract val source: RegularFileProperty

    @get:Input
    abstract val title: Property<String>

    @get:OutputFile
    abstract val target: RegularFileProperty

    @TaskAction
    fun render() {
        target.get().asFile.writeText("# ${title.get()}\n" + source.get().asFile.readText())
    }
}
Kotlin
tasks.register("legacyReport") {
    val src = layout.projectDirectory.file("data.txt")
    val out = layout.buildDirectory.file("report.txt")
    inputs.file(src)
    inputs.property("title", "Sales")
    outputs.file(out)
    doLast { out.get().asFile.writeText(src.asFile.readText().uppercase()) }
}

Common annotations:

Annotation Use for
@Input a value (string, number, enum)
@InputFile, @InputDirectory, @InputFiles file inputs; content is hashed
@Classpath, @CompileClasspath classpaths, ignoring irrelevant jar details
@OutputFile, @OutputDirectory what the task creates
@Internal a property that does NOT affect the result
@PathSensitive whether file paths matter, or only content

If you forget to declare inputs, Gradle cannot know that something changed, and the task runs every time (a task with no outputs is never up to date). If you declare too few, Gradle may wrongly skip it. Both are bugs.

Java Stand-in: up-to-date check with hashes (not Gradle)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The build cache

Up-to-date checks only look at the previous run in the same workspace. The build cache goes further: it stores task outputs under a key made from the task's fingerprint. Any build that computes the same key can restore the output without executing the task.

Enable it in gradle.properties:

TEXT
org.gradle.caching=true

or per run with --build-cache. By default Gradle uses a local cache in ~/.gradle/caches/build-cache-1. In settings.gradle.kts you can add a remote cache shared by CI and developers:

Kotlin
buildCache {
    local { isEnabled = true }
    remote<HttpBuildCache> {
        url = uri("https://cache.company.example/cache/")
        isPush = System.getenv("CI") != null       // only CI writes
        credentials {
            username = providers.environmentVariable("CACHE_USER").orNull
            password = providers.environmentVariable("CACHE_PASSWORD").orNull
        }
    }
}

A good policy is: CI pushes, developers read only. That prevents polluted entries from local experiments.

Task outputs are cacheable only if the task class is annotated with @CacheableTask (as the core Java compile and Test tasks are) and its inputs are fully declared. Tasks that touch the network or the clock should not be cached.

Java Stand-in: a build cache keyed by fingerprint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Finding out why a task re-ran

Add --info to see a reason such as:

TEXT
Task ':compileJava' is not up-to-date because:
  Input property 'options.compilerArgs' has changed.

For cache misses, build with --scan (Develocity build scan) or use the "task inputs" comparison there, or run ./gradlew compileJava -Dorg.gradle.caching.debug=true. Typical causes:

  • Absolute paths or usernames in inputs. Use relative paths and @PathSensitive(RELATIVE).
  • Timestamps or random values written into outputs or passed as inputs (for example a build time in the manifest).
  • Different JDK or OS between machines (part of the key for compile tasks).
  • Undeclared inputs, such as reading an environment variable in doLast.
  • Unstable ordering in generated files.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does UP-TO-DATE next to a task name mean?

    Gradle compares fingerprints of inputs and outputs. If they match the last recorded run, it skips the task.
  2. 2. What is the difference between UP-TO-DATE and FROM-CACHE?

    Up-to-date compares with the previous local execution. The build cache restores outputs keyed by the input fingerprint, even from another build or machine.
  3. 3. What happens to a task that declares no outputs?

    Without declared outputs Gradle cannot verify that the work is already done, so it runs the task.
  4. 4. Which annotation marks a task property that does NOT influence the result?

    @Internal excludes the property from fingerprints, so changing it does not make the task re-run.

Summary

  • Gradle skips tasks whose inputs and outputs match the previous run (UP-TO-DATE).
  • Declare inputs and outputs on custom tasks with annotations or the inputs/outputs DSL.
  • The build cache stores outputs by fingerprint and can restore them across machines (FROM-CACHE).
  • Let CI push to the remote cache and developers only read.
  • Use --info and build scans to find out why a task re-ran or missed the cache.

Next: Daemon, parallel execution and the configuration cache