Lazy Configuration API

A ConfigurableFileCollection is a mutable, lazily-evaluated set of files. You create one with project.objects.fileCollection() and populate it with from(...), so the actual files are resolved later, not at configuration time.

ProjectLayout (project.layout) gives lazy access to the project and build directories. You use layout.buildDirectory.file("name") or .dir("name") to point at outputs under build/ without resolving paths eagerly.

map transforms a provider's value into a new provider using a function, without computing it now. The transform runs lazily only when the value is finally queried, so it stays deferred until execution time.

ObjectFactory is a Gradle service that creates instances of model objects like Property, FileCollection, and custom managed types. You get it via @Inject in a constructor or through project.objects.

ProviderFactory creates lazy Provider values from sources like environment variables, system properties and Gradle properties. You get it via project.providers, or by @Inject in a task/plugin.

Provider<T> is a read-only lazy value you query with get(). Property<T> extends Provider<T> and is also writable — you can set() its value or wire it to another provider.

add/addAll (list/set) and put/putAll (map) append to the property without resolving it. They accept plain values or Providers, and the actual elements are only computed when the property's value is queried.

from(...) appends new sources to whatever is already there; setFrom(...) replaces all existing sources with exactly what you pass. Use from to accumulate, setFrom to reset.

Declare an abstract getter returning ConfigurableFileCollection, annotated with @InputFiles. Gradle manages the instance for you, so you never create or assign it — callers just use from() to set sources.

Declare an abstract val of type RegularFileProperty annotated @get:OutputFile. Set it to layout.buildDirectory.file(...). Gradle tracks that file for up-to-date checks and the build cache, and creates parent dirs.

map's function returns a plain value (T -> R, giving Provider<R>). flatMap's function returns another provider (T -> Provider<R>, also giving Provider<R> by flattening). Use flatMap when your transform itself produces a provider.

A managed type is a class (usually abstract) where Gradle generates the implementation. Abstract getters returning Property/FileCollection/etc. become managed properties Gradle initializes automatically, so you don't write boilerplate or constructors.

providers.environmentVariable returns a lazy, config-cache-tracked Provider. System.getenv() is read eagerly at configuration time and invisible to the configuration cache, so the build can go stale.

get() returns the value or throws if absent. getOrNull() returns the value or null. getOrElse(default) returns the value or the supplied default. Pick based on whether a missing value is an error or has a fallback.

project.buildDir resolves the path eagerly at configuration time, isn't a Provider, and references the Project at execution. That breaks build-dir relocation, up-to-date tracking, and the configuration cache. Use layout.buildDirectory.file()/.dir() instead.

Calling get/getOrElse/getOrNull during configuration, capturing values into local variables, or unwrapping providers inside map lambdas forces eager evaluation and drops dependencies. Stay lazy with map/flatMap/zip/orElse and wire providers directly into task inputs.

Lazy resolution means a value is computed only when read (usually at execution), not when configured. This avoids wasted work for tasks that don't run, lets a value depend on results produced later, and keeps the build configuration-cache friendly.

convention() sets a fallback used only until something is explicitly set. set()/value() replace the whole collection. empty() explicitly resets the property to an empty collection. add/addAll then append on top of whichever base is active.

A DirectoryProperty holds a directory location lazily. From it you call .file("child.txt") or .dir("sub") to get a lazy Provider for nested paths. Use it for @OutputDirectory or a configurable base directory in an extension.

orElse returns a new provider that uses a fallback value or provider when the source is absent, staying lazy. convention sets a default on a Property that an explicit set() overrides. getOrElse eagerly returns a plain value or a default now.

Use providerA.zip(providerB) { a, b -> ... }. It builds a new lazy provider combining both values. If either input is absent, the combiner is skipped and the result is absent.

objects.fileProperty() returns a RegularFileProperty and objects.directoryProperty() a DirectoryProperty — lazy, location-aware wrappers around a file/dir. They defer resolution and track task dependencies, unlike a raw File.

gradleProperty returns a lazy, config-cache-tracked Provider<String> from gradle.properties and -P flags. findProperty/property read eagerly and also see project ext/extra properties, not just Gradle properties.

isPresent is true when a value can be computed — from an explicit set() or a convention. convention() supplies a default used only if nothing is explicitly set; an explicit set() overrides the convention.

They're interfaces with no public constructor. You create a Property via ObjectFactory (project.objects.property(Type::class)) and create read-only Providers via project.provider { ... } or by transforming an existing Provider.

As @Input, a collection property's resolved value is snapshotted for up-to-date checks. Resolution is deferred until just before execution and then finalized, so changes (and contributed providers) are captured. Mutating after finalization throws.

A ConfigurableFileCollection tracks the tasks that produce its files. If you add a task output or a Provider that knows its producer, dependencies are inferred automatically. builtBy() is for the case where you add raw files whose producing task Gradle can't infer.

.elements returns a Provider<Set<FileSystemLocation>> — a lazy view you can map/wire without resolving now. .asFileTree turns the collection into a FileTree so you can walk directory contents recursively and apply include/exclude patterns.

Set the consumer's input property to the producer's output Provider: consumer.input.set(producer.flatMap { it.outputFile }). Because the value is a Provider carrying task info, Gradle wires the dependency automatically — no dependsOn needed.