Shared Configuration

buildSrc is a special directory Gradle automatically compiles into a project and puts on every build script's classpath. You put shared build logic there — custom plugins, tasks, helper classes — without publishing anything.

Each subproject opts in to shared config by listing the convention plugin in its own plugins {} block, e.g. id("myproject.java-conventions"). subprojects {} instead pushes config down from the root onto every subproject implicitly.

Put apply(plugin = "..."), a repositories {} block, and a dependencies {} block inside subprojects {}. Reference configurations like implementation by their string name because typed accessors aren't generated in the root script.

build-logic is a separate Gradle build (a folder with its own settings.gradle) wired in via includeBuild('build-logic'). It holds convention plugins like buildSrc but is an explicit, isolated build instead of an implicit one.

buildSrc output is on every build script's classpath. Changing it changes that classpath, so Gradle must recompile and re-evaluate the build scripts and busts the build-script / configuration cache — making the next build slower everywhere.

Get VersionCatalogsExtension, call .named("libs"), then use findLibrary/findBundle/findVersion/findPlugin (each returns an Optional), .get() it, and pass libraries/bundles to dependencies.add(...).

The type-safe libs.* accessors are generated for build scripts that the catalog is in scope for. Inside a buildSrc convention plugin those generated accessors aren't on the classpath, so libs.* doesn't resolve.

Apply kotlin-dsl in buildSrc/build.gradle.kts, then add a *.gradle.kts file under buildSrc/src/main/kotlin. Its file name (minus the extension) becomes the plugin id, applied via plugins { id("...") }.

Project isolation means a project only reads/mutates its own state, never another project's. subprojects { } / allprojects { } reach into other projects' models from the root, coupling them and breaking that boundary.

Convention plugins are applied by each project to itself, so they preserve project isolation, stay configuration-cache friendly, are explicit and opt-in per project, and are testable/versioned — unlike cross-config that mutates projects from the root.

Each child's build is partly defined in a file it doesn't own (the root), so you can't read a module's script and know its real config. It also forces every module to be configured whenever any is touched, hurting maintainability and laziness.

Applying a plugin configures only the module that applies it, using only inputs the plugin itself knows. subprojects {} reaches across project boundaries at configuration time, coupling projects and breaking the isolation Gradle wants for safe parallel/lazy configuration.

The configuration cache assumes each project's configuration depends only on its own inputs. Cross-configuration makes the root produce other projects' config, breaking that per-project assumption and limiting safe reuse and parallel configuration.

The programmatic lookup key is the original catalog alias (dashes), not the dotted accessor form. Use findLibrary("junit-jupiter"). The dots in libs.junit.jupiter are accessor navigation sugar, not the alias string.

Use project(":path") { ... } to target one named subproject, or filter inside subprojects {} with a condition like if (name.startsWith("feature-")). allprojects/subprojects are the all-or-nothing versions.

buildSrc adds its jar to every build script's classpath (simple but global, and changes invalidate broadly). build-logic is consumed by id only where applied, giving narrower caching impact and explicit dependencies, at the cost of more setup.

Write a class extending DefaultTask under buildSrc/src/main/kotlin with @Input/@OutputFile-annotated properties, then in any module use tasks.register<MyTask>("name") to register and configure it.

List several plugin ids in the module's plugins {} block — e.g. a base java-conventions plus a more specific application-conventions or library-conventions. The module applies only the presets matching its role.

Apply the convention plugin as usual, then add a normal configuration block in that one module's build script that resets the specific value — e.g. set java.toolchain to a higher version after the plugin runs.

Gradle is deprecating code that reaches into and changes another project's model from outside it — exactly what subprojects { }/allprojects { } and project(":x") { ... } blocks do. The fix is self-applied convention plugins.

buildscript {} configures the build's own classpath/repositories (where Gradle finds plugins to apply). allprojects {}/subprojects {} configure the projects (their dependencies, plugins, settings). They solve different problems and aren't interchangeable.

buildSrc output is on every build script's classpath, so any change there can invalidate the whole build's caching. build-logic is a separate build consumed by plugin id, so changes touch only the dependent plugin paths.

Create build-logic/ with its own settings.gradle.kts, move convention plugin sources in, apply kotlin-dsl, add includeBuild('build-logic') to the root settings, then change subprojects to apply the plugins by id. Delete buildSrc once migrated.

Because build-logic is a real build with java-gradle-plugin projects, you can publish its convention plugins to a Maven repo and apply them from other repos by id. buildSrc is local-only and can't be published or reused outside its build.

By adding the catalog's generated accessor as a dependency of the build-logic build — declaring the catalog in dependencyResolutionManagement of build-logic's own settings and adding implementation(files(libs.javaClass...))/the generated dependency — so the accessor class lands on the plugin's compile classpath.

Don't dump churny or production code in buildSrc, don't let it grow huge (every change rebuilds the world), avoid eager cross-project configuration from it, and keep its dependency surface tight. For big repos, graduate to a build-logic composite build.

Group the subprojects {} config by concern, expose each group as a convention plugin id, then add the matching ids to each module's plugins {} block and delete the root block. Watch for modules that quietly relied on root-injected config.

subprojects { } eagerly visits every project, often forcing afterEvaluate hooks and order-dependent code that's fragile. Convention plugins configure one project lazily with configureEach/register, removing the ordering traps.

named(name) must match the catalog's declared name exactly. If you have multiple or a custom name, pass that name; to be defensive, check catalogNames/find(name) first, or iterate, instead of assuming "libs".