Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Projects and Tasks

Inputs, Outputs and Up-to-date Checks in Gradle

See how Gradle decides to skip work: declare task inputs and outputs, use @InputFiles and @OutputDirectory, and understand fingerprints and the build cache.

Gradle's speed comes from not doing work twice. For a task to be skippable, Gradle must know what the task reads (inputs) and what it writes (outputs). Before running, it fingerprints both; if they match the previous run, the task is UP-TO-DATE and is skipped. Tasks from plugins already declare this. When you write your own tasks, declaring inputs and outputs is what turns a slow script into a proper incremental build.

The Gradle code here is read-only. A runnable Java stand-in implements a fingerprint-based up-to-date check so you can see exactly how the decision is made.

The problem with an undeclared task

Kotlin
tasks.register("generateVersionFile") {
    doLast {
        val out = layout.buildDirectory.file("version.txt").get().asFile
        out.parentFile.mkdirs()
        out.writeText("version=${project.version}")
    }
}

This task works, but Gradle knows nothing about it. It runs every single time, because without declared inputs and outputs Gradle cannot prove it is safe to skip. That is wasteful, and worse, anything that depends on its output also reruns.

Declaring inputs and outputs

Kotlin
tasks.register("generateVersionFile") {
    val versionValue = project.version.toString()
    val outFile = layout.buildDirectory.file("version.txt")

    inputs.property("version", versionValue)
    outputs.file(outFile)

    doLast {
        val f = outFile.get().asFile
        f.parentFile.mkdirs()
        f.writeText("version=$versionValue")
    }
}

Now the first run shows > Task :generateVersionFile, and the second shows > Task :generateVersionFile UP-TO-DATE. Change version in the build script and it runs again, because the input property changed. Delete build/version.txt and it runs again, because the output is missing.

The inputs API has several flavors:

API Meaning
inputs.property("k", v) a simple value (string, number, boolean, list)
inputs.file(f) / inputs.files(...) one or more files whose content matters
inputs.dir(d) a directory tree of files
outputs.file(f) / outputs.dir(d) what the task produces

Typed tasks use annotations

Real reusable tasks are classes. Annotations declare inputs and outputs once, and Gradle checks them for correctness:

Kotlin
abstract class GenerateGreeting : DefaultTask() {
    @get:Input
    abstract val greeting: Property<String>

    @get:InputFile
    @get:PathSensitive(PathSensitivity.NONE)
    abstract val template: RegularFileProperty

    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    @TaskAction
    fun generate() {
        val text = template.get().asFile.readText().replace("{{greeting}}", greeting.get())
        outputFile.get().asFile.writeText(text)
    }
}

Common annotations: @Input, @InputFile, @InputFiles, @InputDirectory, @OutputFile, @OutputDirectory, @Internal (not part of up-to-date checks), @Optional, and @Classpath / @CompileClasspath for classpath inputs. If you forget an annotation, ./gradlew validatePlugins (for plugin builds) or a run with --info reports it. See custom task types.

How the check works

flowchart TD
  A["Before running a task"] --> B["Fingerprint inputs and outputs"]
  B --> C{"Same as last execution?"}
  C -- "yes" --> D["UP-TO-DATE, skip"]
  C -- "no" --> E{"Output in build cache?"}
  E -- "yes" --> F["FROM-CACHE, restore"]
  E -- "no" --> G["Run the task"]
  G --> H["Store new fingerprints (and cache entry)"]

Fingerprints hash file contents (not timestamps), property values and the task's own implementation.

Key details:

  • Content, not time. Touching a file without changing it does not rerun anything.
  • The task's code is an input. If you change the task class or its action, Gradle reruns it.
  • Outputs are checked too. If someone edits or deletes the output, the task reruns and repairs it.
  • Path sensitivity. PathSensitivity.RELATIVE ignores the absolute folder, which allows cache hits across machines.

Stand-in: a fingerprint check

This program is not Gradle. It hashes input text and an "output" value, and decides whether a task can be skipped.

Java Stand-in: up-to-date check with SHA-256

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.

Expected pattern: run, UP-TO-DATE, run (input changed), run (output missing), UP-TO-DATE. The hashes are the same each time you press Run.

Stand-in: only changed files

Gradle's incremental tasks can go further and process only the files that changed. The stand-in keeps a map of last-seen hashes per file and reports which ones need work.

Java Stand-in: which inputs changed?

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.

In real Gradle you implement this with InputChanges in a @TaskAction method; plugins such as the Java compiler use it for incremental compilation.

Build cache in one paragraph

With --build-cache (or org.gradle.caching=true in gradle.properties), Gradle also stores task outputs under a key made from the inputs. A later build, even on another machine or CI, finds the key and restores the outputs (FROM-CACHE) instead of running the task. This only works for tasks that declare complete inputs and are deterministic, which is why correct declarations matter. See the performance chapter for details.

Checklist for your own tasks

  1. Everything the task reads is an input; everything it writes is an output.
  2. Outputs live under build/, never in src/.
  3. No hidden inputs (environment variables, the current date, network calls) unless declared as inputs.property.
  4. Two tasks must not write to the same output location.
  5. Annotate with @Internal anything that does not affect results (logging flags).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a task without declared outputs run every time?

    Without inputs and outputs, there is nothing to compare, so Gradle never marks the task up to date.
  2. 2. What does Gradle fingerprint for inputs?

    It hashes contents and values. Touching a file without changing it does not trigger a rerun.
  3. 3. Which annotation marks a property that should NOT be part of up-to-date checks?

    @Internal is for properties that do not influence the result, such as a logging option.
  4. 4. You delete the output file of an UP-TO-DATE task. What happens on the next build?

    Outputs are part of the check. A missing or changed output makes the task out of date.

Summary

  • Declare what a task reads (inputs) and writes (outputs) so Gradle can skip it when nothing changed.
  • Use inputs.property/file/dir and outputs.file/dir in scripts, or @Input, @InputFile, @OutputFile in task classes.
  • Fingerprints are content-based and include the task's implementation.
  • Matching fingerprints give UP-TO-DATE; a build cache hit gives FROM-CACHE.
  • Avoid hidden inputs and shared outputs.

Next: Custom Task Types