Gradle Tasks, Task Graph, Dependencies, Ordering, Inputs, Outputs, and Incremental Work: Configuration, Design Choices, and Tradeoffs

1. Design starts with correctness semantics, not the shortest DSL

Task APIs are expressive enough to model several superficially similar relationships. Production builds become fragile when the author chooses the construct with the shortest syntax rather than the one whose semantics match the data flow.

Use this decision sequence: What output/result is required? Who owns it? What exact state affects it? Does another task have to be selected? Can the work be repeated from scratch? Does workspace location matter?

2. Dependency edge versus ordering-only rule

Choose dependsOn when B is not correct unless A has run or its modeled output is available. Choose mustRunAfter when A and B are independently meaningful but cannot safely overlap/order arbitrarily when co-selected. Use shouldRunAfter only when the order is a preference rather than a correctness condition.

3. Ad-hoc doLast task versus typed task

An ad-hoc registered task is excellent for small, repository-local orchestration. A typed task becomes preferable when the behavior is reused, has several typed inputs/outputs, needs validation annotations, or implements file-level incrementality.

Typed does not automatically mean correct. A typed task can still read undeclared state or write overlapping outputs. The annotations/properties must reflect actual behavior.

4. Coarse output directory versus precise output ownership

Declaring the entire build/generated directory as the output of several unrelated tasks creates overlapping ownership. Gradle cannot safely reason about which task produced which files, and cache reuse/parallel execution become harder or unsafe.

Prefer one owner per output location. If tasks collaborate, give each its own subdirectory or model producer outputs as inputs to an aggregation task.

Good ownership:
build/generated/schema/      <- generateSchema owns it
build/generated/client/      <- generateClient owns it
build/reports/aggregate.txt  <- aggregateReport owns it

Risky ownership:
build/generated/             <- generateSchema + generateClient both claim/write it

5. Simple rerun versus true incremental transformation

Do not add InputChanges because “incremental sounds faster.” First measure the task. If it processes ten tiny files in milliseconds, a clear full rebuild may cost less than maintaining removal logic, path normalization, and partial-output correctness.

6. Path sensitivity is a semantic contract, not a performance toggle

ABSOLUTE can make identical content appear different after workspace relocation. NONE can make different filenames appear equivalent when they should not. Pick the weakest sensitivity that is still semantically true—not the weakest one that produces a desired cache result.

For a directory transformer that preserves relative paths, RELATIVE is usually a natural model: docs/a.txt and src/a.txt are distinct within the root, while /agent-1/work/repo versus /agent-2/work/repo is irrelevant.

7. Distinguish task state from other build/platform state

8. Worked decision: code generator in CI

A team has generateApi, compileJava, and lintGenerated. The generator consumes schema/*.yaml and writes Java files. Compilation needs generated Java. Lint is useful but can run independently on an existing generated tree.

9. Tradeoff matrix for a production review

10. Production rule: optimize the model you can explain

A reviewable task graph lets CI choose a smaller correct scope, reason about parallelism, and reuse work safely. If a team cannot explain why a task was skipped or rerun using declared state, the optimization is too opaque or the model is incomplete.

Knowledge check

Official references and version notes

• Gradle 9.7.1 Release Notes — pinned Gradle baseline for this chapter.
• Creating and Registering Tasks and Understanding Tasks.
• Controlling Task Execution — dependencies, ordering rules, finalizers, skip behavior, and task graph semantics.
• Incremental Build — task inputs/outputs, validation, path sensitivity, inferred dependencies, and up-to-date checks.
• Advanced Tasks — InputChanges, incremental file changes, @Incremental, and normalized paths.
• Implementing Custom Tasks — typed task properties and annotations.
• Incremental Builds and Build Caching Basic — task outcome labels such as UP-TO-DATE and FROM-CACHE.
• Build Cache — disabled by default; separate from workspace up-to-date state.
• Build Cache Concepts — repeatable outputs, path normalization, and why overlapping outputs are unsafe for reuse.

Version snapshot: Generated for August 24, 2026 with Gradle 9.7.1, JDK 21 as the Gradle runtime, and Java 17 as the course JVM target. Re-check current Gradle documentation before carrying version-sensitive behavior into future production builds.