Authoring Plugins

Create small, single-responsibility convention plugins (base, library, application, test, publishing) and compose them by applying lower-layer ones inside higher-layer ones. Avoid one monolithic plugin and avoid leaking module-specific logic into shared conventions.

ProjectBuilder only covers the configuration phase in-process: no task execution, no real lifecycle/afterEvaluate, no real dependency resolution or configuration cache. So you pair broad ProjectBuilder wiring tests with focused TestKit tests for execution and lifecycle.

Build a root with ProjectBuilder.builder().build(), then children with .withParent(root).withName("child").build(). ProjectBuilder doesn't auto-evaluate, so afterEvaluate won't fire unless you trigger evaluation via internal APIs (ProjectInternal.evaluate()).

Don't do expensive or side-effecting work in apply — no I/O, no resolving configurations, no eager tasks.create or forcing Property.get(). Register tasks lazily, wire Providers, and defer real work to task actions executed only when needed.

Gradle injects services into a plugin via an @Inject constructor — e.g. ObjectFactory, ProjectLayout, ProviderFactory. You use them to create Property/Provider instances and resolve paths lazily, which is cleaner and configuration-cache friendly.

Apply it via plugins {} in settings.gradle(.kts). The catch: the plugin must already be resolvable when settings is evaluated, so it comes from buildSrc, an included build under pluginManagement, or a published plugin in pluginManagement repositories.

includeBuild(path) in a settings plugin wires another Gradle build into this one as a composite build. Gradle substitutes published dependencies with the included build's projects, letting you develop and consume a library or plugin together without publishing.

Call withGradleVersion("8.5") on GradleRunner to run the build under a specific Gradle version. Parameterize the test over several versions to prove your plugin works across the range you support.

Give each test a fresh temporary project directory (e.g. JUnit @TempDir), write its build/settings files there, and assert against it. TestKit runs in an isolated worker with its own Gradle user home, so tests don't depend on your machine.

A TypeValidationProblem is a single issue validatePlugins found on a task or plugin type — most often a property with no input/output annotation, or conflicting annotations like both @Input and @OutputFile on one getter.

Yes. Declare each plugin as a separate entry in the gradlePlugin { plugins { … } } block with its own id, implementationClass, displayName, description, and tags. One publishPlugins run uploads all of them.

Beyond include and resolution blocks, a Settings plugin can use settings.gradle hooks like settingsEvaluated, projectsLoaded, and projectsEvaluated, configure buildCache, set rootProject properties, enableFeaturePreview, and iterate rootProject to apply per-project conventions.

Use Gradle's external-plugin validation (a ValidatePlugins-style task pointed at the plugin classes/jars rather than your own sources). It runs the same TypeValidationProblem checks on third-party or downstream plugins so you can gate them in CI.

Apply java-gradle-plugin everywhere, enable failOnWarning and enableStricterValidation through a shared convention plugin, run validatePlugins in CI on every plugin repo, and validate published artifacts for third-party plugins.