Gradle Knowledge Patch

Gradle Knowledge Patch

Use this skill when upgrading, configuring, debugging, or extending Gradle builds. Start with the project wrapper version and the plugins actually applied, then use the reference that matches the work at hand.

How to use this patch

1. Read gradle/wrapper/gradle-wrapper.properties before proposing version-sensitive syntax.
2. Inspect settings.gradle(.kts), root and convention-plugin build scripts, and gradle.properties for active feature flags.
3. For a Gradle 9 upgrade, apply the breaking-change checklist before introducing newer APIs.
4. Preserve lazy configuration: prefer providers, register, role-based configuration factories, and deferred publication inputs.
5. Distinguish daemon JVM requirements from Java compilation and test toolchains.
6. Verify report consumers when changing test engines, report structures, timestamps, attachments, or aggregation.
7. Treat incubating APIs and feature previews as opt-in behavior that can still change.

Reference index

Breaking changes first

Gradle 9 runtime and language baselines

• Run the daemon on Java 17 or newer. Older targets remain available through Java toolchains.
• Expect embedded Kotlin 2.2 and Groovy 4 behavior in scripts and build logic.
• Check plugin compatibility floors before changing the wrapper, especially Kotlin DSL, Android, and enterprise build plugins.
• Ensure every included project maps to an existing writable directory.

See Gradle 9 upgrade for exact compatibility floors and migration details.

Removed build-layout and convention APIs

Do not use -c/--settings-file, -b/--build-file, GradleBuild.buildFile, or the removed Convention APIs. Use standard settings and build locations, extensions, direct task configuration, and the base extension.

Replace removed Kotlin DSL domain-object shortcuts and eager provider access. Apply Develocity by explicit plugin ID, stop relying on removed bundled Groovy modules and org.gradle.util helpers, and replace removed process helpers in build logic.

Test tasks require explicit intent

Custom Test tasks no longer inherit the built-in test source set. Set testClassesDirs and classpath, or model the target with JVM test suites. A test task with sources, no filters, and no discovered tests now fails unless failOnNoDiscoveredTests is deliberately disabled.

Archive and artifact lifecycle behavior

Archives are reproducible by default. Filesystem order, timestamps, and permissions are no longer preserved unless explicitly requested. Standard EAR, WAR, and Java artifacts join assemble and archives, but artifacts on custom visible configurations require explicit lifecycle wiring.

API and nullability migrations

Gradle API nullness annotations use JSpecify. Kotlin extensions over Provider<T> commonly require T : Any, and nullable Property declarations may no longer type-check. Injected getters on Gradle subclasses require abstract classes; account for RootComponentIdentifier and unknown future component identifiers.

Configuration Cache quick reference

Enabling, suppressing, and troubleshooting

Gradle 9 suggests Configuration Cache for compatible builds but does not force it. Set org.gradle.configuration-cache=false to suppress the suggestion. Known unsupported features can fall back automatically; task-execution cache problems still abort.

Use the integrity check only for diagnosis because it increases cache size and read/write cost:

org.gradle.configuration-cache.integrity-check=true

Read-only mode consumes hits without storing misses:

./gradlew --configuration-cache -Dorg.gradle.configuration-cache.read-only=true

Correctness rules

• Register onTaskCompletion listeners through a registered build service provider.
• Incompatible tasks discard the entry even when cache problems are warnings.
• Environment-backed project properties only invalidate an entry if configuration actually read them.
• Startup -javaagent: agents work in normal daemons and TestKit's default daemon mode; dynamic attachment and embedded TestKit mode do not.
• A whole ResolutionResult can be a task @Input while Configuration Cache is active.

See Configuration Cache and laziness for flags, provider patterns, and Isolated Projects migration.

Common workflows

Select and provision daemon JVMs

Daemon JVM criteria can auto-provision a missing JDK when a resolver is configured. Native Image-capable JDKs can be required for Java or daemon toolchains. JAVA_HOME participates in toolchain auto-detection, and daemon toolchains are stable APIs.

Keep the daemon runtime separate from compile/test toolchains. Use updateDaemonJvm to materialize cross-platform daemon criteria and download URLs. See Daemon, CLI, Wrapper, and platforms.

Keep configuration lazy

Prefer these patterns:

configurations {
    val parent = dependencyScope("parent")
    resolvable("child") {
        extendsFrom(parent)
    }
}

Use AttributeContainer.addAllLater(...) for deferred attribute merging, provider overloads when publishing configuration variants, and DomainObjectCollection.elements when wiring a collection to task inputs without realization.

Run unattended and diagnostic builds

• --non-interactive disables prompts; org.gradle.console.interactive=false persists the choice.
• NO_COLOR disables color while retaining rich-console behavior; --console=colored provides color without progress UI.
• --task-graph prints requested tasks and dependencies without execution.
• tasks --provenance and help --task identify where tasks were registered.
• --warning-mode=all renders structured problems and lifts the source-location cap.

Configure modern test reporting

Gradle reports framework hierarchy, parameterized invocations, metadata, and attachments with stronger source attribution. Non-class JUnit Platform engines can supply testDefinitionDirs, and custom runners can use TestEventReporterFactory. Aggregate reports keep each source separate rather than merging identical structures.

When consuming JUnit XML, accept millisecond timestamps, nested-class filenames, properties emitted from test data, and attachment markers. See Testing, reports, and quality tools.

Publish components and distributions

Create ad hoc software components through the publishing extension's softwareComponentFactory. Pass Provider<ConsumableConfiguration> values to preserve laziness. Use distribution-base when a plugin needs distribution support without an automatic main distribution.

POM distribution management, signing behavior, distribution signatures, dependency-verification diagnostics, and repository-failure behavior are covered in Dependencies, publishing, and distributions.

Author plugins and integrations

• Strongly typed dependency blocks have partially stable APIs, except version-catalog dependencies.
• ProblemSpec.additionalData(...) and Tooling API typed views carry structured custom diagnostics.
• Stream Tooling API and TestKit output rather than materializing large results.
• ProjectLayout.settingsDirectory resolves build-wide files without reaching through rootProject.
• Precompiled Kotlin Settings plugins can receive generated accessors from kotlin-dsl.
• Lock domain-object collection membership with disallowChanges() without realizing lazy entries.

See Tooling API, Problems API, and build logic.

Upgrade verification checklist

After changing a Gradle wrapper or build feature:

1. Run ./gradlew help to validate settings, included-project paths, and plugin application.
2. Run ./gradlew tasks --all and inspect unexpected configuration realization or task registration.
3. Run the relevant test tasks with --warning-mode=all; inspect console, HTML, and XML output.
4. Exercise Configuration Cache twice: the first run stores and the second loads an entry.
5. Verify archives for deterministic order, timestamp, and permissions expected by consumers.
6. Publish to a local repository and inspect Gradle Module Metadata, POM content, variants, and signatures.
7. Run integration tests through the same TestKit daemon mode used in CI.
8. Check Wrapper authentication, timeout, and retry settings without exposing credentials to unrelated hosts.

Compatibility judgment

Prefer the wrapper, applied plugin versions, source code, and observed task behavior over assumptions. If a build is newer than this patch's frontmatter version, use the guidance only for features known to exist in the project's actual Gradle version and verify current behavior before changing the build.