Authoring Task Types

It's a small object that supplies command-line arguments lazily via asArguments(). You register it on a task (e.g. JavaExec/Test) so the actual arguments are computed at execution time rather than hardcoded as plain strings.

DefaultTask is Gradle's base class for tasks. You create a custom task type by subclassing it and adding one method annotated with @TaskAction, which holds the work the task runs when executed.

dependsOn declares that one task requires another to run first; if you ask for task A, Gradle also runs its dependencies. A pure ordering hook only sequences tasks that are already scheduled — it never adds a task to the build.

They tell Gradle which properties are a task's inputs and outputs so Gradle can decide if the task is up-to-date and skip running it when nothing relevant changed.

Absolute paths differ per machine/checkout, so absolute path sensitivity makes the cache key machine-specific and kills cross-machine hits. Cacheable tasks should use RELATIVE (or NAME_ONLY/NONE) so the key reflects content, not location.

The task's provider collection is annotated @Nested, so Gradle recursively scans each provider's own @Input/@InputFile properties and folds them into the task's input fingerprint. That's how dynamic args participate in up-to-date checks.

Constructor code runs at configuration time (every build, whenever the task is realized). @TaskAction code runs at execution time, only when the task actually runs. Put the real work in @TaskAction, not the constructor.

Register a task type with tasks.register("name", MyTask::class) { ... }. Prefer register over create because register is lazy: the task is only configured if it is actually needed, which speeds up configuration.

If you connect a producing task's output Provider (e.g. its RegularFileProperty) directly to a consuming task's input property, Gradle sees the output 'carries' its producing task and automatically adds the dependency — no manual dependsOn needed.

ADDED and MODIFIED mean regenerate the output for that file; REMOVED means delete the output that file produced. If you ignore REMOVED, deleted sources leave stale generated outputs behind, so the output directory no longer matches the inputs.

A task that, when re-run, processes only the input files that changed since the last run instead of all of them. You author one to avoid redoing work for the whole input set when a few files changed.

@Input snapshots a scalar value (string, number, enum). @InputFile/@InputFiles/@InputDirectory track file or directory content by hashing the bytes. Use @Input for plain values, the file annotations when a File/FileCollection's content matters.

@PathSensitive tells Gradle which part of a file's path counts when fingerprinting an input. With RELATIVE, only the relative path plus content matters, so moving the project directory still hits the cache.

@Classpath fingerprints a list of jars by content but ignores order-insensitive path noise and applies jar-aware normalization. @CompileClasspath goes further, hashing only the public ABI of classes so non-API changes don't bust the cache.

A normal task with declared inputs/outputs is skipped entirely if nothing changed, but re-runs fully if anything changed. An incremental task re-runs but processes only the changed files. The complexity is justified when per-file work is expensive and only a few of many files change.

Using Property/Provider keeps the values lazy: they're resolved when asArguments() runs at execution time, so later configuration changes and convention/defaults are picked up. Capturing plain values early freezes stale or unconfigured data.

a.finalizedBy(b) schedules b to run after a, even if a fails. It's used for guaranteed cleanup or teardown — like stopping a server or collecting reports — that must happen whether or not the main task succeeded.

Both only order tasks that are already scheduled, never adding tasks. mustRunAfter is a hard ordering constraint Gradle always honors. shouldRunAfter is a soft preference Gradle can break to avoid a cycle or to enable more parallelism.

@LocalState marks a directory or file holding a task's intermediate, machine-specific state. Gradle tracks it for up-to-date checks but does NOT store it in the build cache, because it shouldn't be shared across machines.

Use @OutputFiles/@OutputDirectories when a task produces multiple, dynamically-keyed outputs. Backing the property with a Map<String, File> gives each output a stable identity key, which Gradle uses for reliable up-to-date checks and overlapping-output handling.

@Internal marks a property as deliberately NOT part of inputs/outputs, so it's excluded from up-to-date checks. @Optional says an input/output property is allowed to be unset/null without failing validation.

@IgnoreEmptyDirectories drops empty directories from the input fingerprint so they don't trigger reruns. @NormalizeLineEndings hashes text files ignoring CRLF vs LF differences, so a line-ending-only change doesn't bust the cache.

@DisableCachingByDefault marks a task type as intentionally not cacheable and records a reason, so it isn't a candidate for caching and validation won't nag about it. It's the explicit opposite of @CacheableTask.

The key hashes the task's implementation (type + classpath), each @Input value, and the fingerprint of all file inputs. Any difference — a changed annotation processor, a different input file content/path, or a plugin upgrade — changes the key.

Track the file via @InputFile/@Classpath with an appropriate @PathSensitivity (often NONE or RELATIVE) so the cache key depends on content, not the absolute path. The absolute path appears only in the returned argument string, which isn't fingerprinted.

Declaring a task abstract lets Gradle generate the concrete subclass at runtime. Gradle supplies implementations for abstract managed-property getters (like Property) and injects services through @Inject constructor params or abstract getters.

Task dependencies are computed at graph-construction time, not execution time. To make them dynamic you pass a Callable/closure or Provider to dependsOn, or implement Buildable.getBuildDependencies() on an input value so the value 'carries' the tasks that build it.

Real artifacts → @OutputFiles/@OutputDirectories. The incremental scratch directory → @LocalState (tracked, not cached). The wipe task's deleted path → @Destroys so it never races the producer under --parallel. Inputs stay @Input/@InputFiles with path sensitivity.

@Destroys marks a path a task removes (e.g. a clean task deleting build/). Gradle uses it to schedule destroyer tasks so they never overlap with tasks that produce or consume those same paths, preventing data races in parallel builds.