Standalone Plugin Development in Practice: Extension DSL Pass-through and Registration

Standalone Gradle plugins are engineered to encapsulate complex, reusable, highly testable, and publicly publishable build capabilities. Unlike internal build-logic, they are compiled, tested, and published as independent libraries, and are subsequently applied by multiple consumer projects via a plugin ID.

The core architectural challenge of standalone plugin development is not "how to write a Plugin<Project> interface," but rather how to design an impeccable Extension DSL. The DSL must empower users to express their intent clearly, while strictly adhering to Gradle's lazy configuration, incremental build mechanics, and Configuration Cache compatibility.

Structure of a Standalone Plugin Project

A minimal Kotlin-based standalone plugin project:

my-gradle-plugin/
├── settings.gradle.kts
├── build.gradle.kts
└── src/
    ├── main/kotlin/
    │   ├── ApiGuardExtension.kt
    │   ├── ApiGuardPlugin.kt
    │   └── ApiGuardTask.kt
    └── test/kotlin/
        └── ApiGuardPluginTest.kt

The build script:

plugins {
    `java-gradle-plugin`
    `kotlin-dsl`
}

gradlePlugin {
    plugins {
        create("apiGuard") {
            id = "club.zerobug.api-guard"
            implementationClass = "club.zerobug.gradle.ApiGuardPlugin"
        }
    }
}

The java-gradle-plugin autonomously generates the required plugin marker metadata, enabling consumers to flawlessly apply it using plugins { id("club.zerobug.api-guard") version "..." }.

Extensions Are the Public Contract

You must never compel users to reach into your plugin to directly mutate internal tasks:

// ANTI-PATTERN
tasks.named<ApiGuardTask>("apiGuard") {
    // Exposes internal task names; refactoring this will break consumer scripts
}

Instead, provide a stable, strongly-typed extension:

abstract class ApiGuardExtension @Inject constructor(objects: ObjectFactory) {
    val enabled: Property<Boolean> = objects.property(Boolean::class.java)
    val apiFile: RegularFileProperty = objects.fileProperty()
    val failOnChange: Property<Boolean> = objects.property(Boolean::class.java)
}

Plugin implementation:

class ApiGuardPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create(
            "apiGuard",
            ApiGuardExtension::class.java
        )

        // Establish logical default conventions
        extension.enabled.convention(true)
        extension.failOnChange.convention(true)
        extension.apiFile.convention(
            project.layout.projectDirectory.file("api/current.txt")
        )

        // Lazily wire the extension providers directly into the task inputs
        project.tasks.register<ApiGuardTask>("apiGuard") {
            enabledFlag.set(extension.enabled)
            apiFile.set(extension.apiFile)
            failOnChange.set(extension.failOnChange)
        }
    }
}

Critically, this logic does not read the extension values during the configuration phase. It passes the Provider mapping directly to the task. When the user subsequently configures the extension in their build script, the task resolves the final value automatically.

Task Fields Must Not Retain the Project Instance

Task implementations must remain mathematically serializable and cacheable:

abstract class ApiGuardTask : DefaultTask() {
    @get:Input
    abstract val enabledFlag: Property<Boolean>

    @get:InputFile
    @get:PathSensitive(PathSensitivity.RELATIVE)
    abstract val apiFile: RegularFileProperty

    @get:Input
    abstract val failOnChange: Property<Boolean>

    @TaskAction
    fun run() {
        if (!enabledFlag.get()) {
            logger.lifecycle("apiGuard disabled")
            return
        }

        val file = apiFile.get().asFile
        if (!file.exists() && failOnChange.get()) {
            throw GradleException("API file does not exist: ${file.path}")
        }
    }
}

It is an architectural violation to save references to Project, Configuration, or SourceSetContainer within task fields. These objects belong exclusively to the configuration-time model and are utterly forbidden from entering the execution-time task state. Every parameter required by the task action must be injected strictly as a Property or file attribute.

How Plugins React to Other Plugins

Standalone plugins frequently need to inject varying logic depending on whether the Android, Java, or Kotlin plugins are present. Never assume a fixed plugin application sequence:

// ANTI-PATTERN: Fails if the Android plugin is applied AFTER your plugin
project.plugins.withId("com.android.application") {
    configureAndroidApp(project, extension)
}

project.plugins.withId("java-library") {
    configureJavaLibrary(project, extension)
}

The plugins.withId closure expresses a reactionary intent: "Execute this configuration only if and when this plugin is present." It is infinitely safer than attempting to query the extension immediately inside apply, because consumers have the liberty to apply your plugin before applying the Android plugin.

TestKit Verifies Actual Build Behavior

Unit testing a plugin by invoking raw functions is insufficient. Gradle TestKit provisions a sterile, temporary directory, synthesizes a build script, and executes a full Gradle daemon against it:

class ApiGuardPluginTest {
    @Test
    fun `registers api guard task`() {
        val projectDir = Files.createTempDirectory("api-guard-test").toFile()
        projectDir.resolve("settings.gradle.kts").writeText("")
        projectDir.resolve("build.gradle.kts").writeText(
            """
            plugins {
                id("club.zerobug.api-guard")
            }
            """.trimIndent()
        )

        val result = GradleRunner.create()
            .withProjectDir(projectDir)
            .withArguments("tasks", "--all")
            .withPluginClasspath()
            .build()

        assertTrue(result.output.contains("apiGuard"))
    }
}

The unparalleled value of TestKit is its ability to holistically verify plugin markers, script compilation, task registration, DSL resolution, and Configuration Cache compliance across genuine execution pathways. Without this, a plugin might pass standard unit tests but immediately detonate in production due to a subtle AGP version incompatibility.

Publishing and Compatibility Strategies

A standalone plugin must manage its compatibility matrix as rigorously as a public API:

• Once published, a Plugin ID is immutable. Do not casually alter it.
• Extension fields must only evolve via addition; deprecations and renames require extensive grace periods.
• Explicitly document the supported boundaries for Gradle, AGP, and Kotlin versions.
• Never directly depend on internal Gradle APIs or obfuscated com.android.build.gradle.internal packages.
• Implement stringent CI checks to flag calls to deprecated Gradle APIs.

Build plugins execute globally on every developer's machine and CI pipeline. A compatibility fracture will instantly paralyze the delivery velocity of your entire consumer base. It is always preferable to engineer a conservative API rather than exposing volatile, internal objects to users.

Engineering Risks and Observability Checklist

Once Custom Plugin logic enters a live Android monorepo, the paramount risk is not a trivial API typo; it is the catastrophic loss of build explainability. A minuscule change might trigger a massive recompilation storm, CI might spontaneously timeout, cache hits might yield untrustworthy artifacts, or a shattered variant pipeline might only be discovered post-release.

Therefore, mastering this domain requires constructing two distinct mental models: one explaining the underlying mechanics, and another defining the engineering risks, observability signals, rollback strategies, and audit boundaries. The former explains why the system behaves this way; the latter proves that it is behaving exactly as anticipated in production.

Key Risk Matrix

Metrics Requiring Continuous Observation

• Does configuration phase latency scale linearly or supra-linearly with module count?
• What is the critical path task for a single local debug build?
• What is the latency delta between a CI clean build and an incremental build?
• Remote Build Cache: Hit rate, specific miss reasons, and download latency.
• Configuration Cache: Hit rate and exact invalidation triggers.
• Are Kotlin/Java compilation tasks wildly triggered by unrelated resource or dependency mutations?
• Do resource merging, DEX, R8, or packaging tasks completely rerun after a trivial code change?
• Do custom plugins eagerly realize tasks that will never be executed?
• Do build logs exhibit undeclared inputs, overlapping outputs, or screaming deprecated APIs?
• Can a published artifact be mathematically traced back to a singular source commit, dependency lock, and build scan?
• Is a failure deterministically reproducible, or does it randomly strike specific machines under high concurrency?
• Does a specific mutation violently impact development builds, test builds, and release builds simultaneously?

Rollback and Downgrade Strategies

• Isolate build logic commits from business code to enable merciless binary search (git bisect) during triaging.
• Upgrading Gradle, AGP, Kotlin, or the JDK demands a pre-verified compatibility matrix and an immediate rollback version.
• Quarantine new plugin capabilities to a single, low-risk module before unleashing them globally.
• Configure remote caches as pull-only initially; only authorize CI writes after the artifacts are proven mathematically stable.
• Novel bytecode instrumentation, code generation, or resource processing logic must be guarded by a toggle switch.
• When a release build detonates, rollback the build logic version immediately rather than nuking all caches and praying.
• Segment logs for CI timeouts to ruthlessly isolate whether the hang occurred during configuration, dependency resolution, or task execution.
• Document meticulous migration steps for irreversible build artifact mutations to prevent local developer state from decaying.

Minimum Verification Matrix

Audit Questions

1. Does this specific block of build logic possess a named, accountable owner, or is it scattered randomly across dozens of module scripts?
2. Does it silently read undeclared files, environment variables, or system properties?
3. Does it brazenly execute heavy logic during the configuration phase that belongs in a task action?
4. Does it blindly infect all variants, or is it surgically scoped to specific variants?
5. Will it survive execution in a sterile CI environment devoid of network access and local IDE state?
6. Have you committed raw credentials, API keys, or keystore paths into the repository?
7. Does it shatter concurrency guarantees, for instance, by forcing multiple tasks to write to the exact same directory?
8. When it fails, does it emit sufficient logging context to instantly isolate the root cause?
9. Can it be instantaneously downgraded via a toggle switch to prevent it from paralyzing the entire project build?
10. Is it defended by a minimal reproducible example, TestKit, or integration tests?
11. Does it forcefully inflict unnecessary dependencies or task latency upon downstream modules?
12. Will it survive an upgrade to the next major Gradle/AGP version, or is it parasitically hooked into volatile internal APIs?

Anti-pattern Checklist

• Weaponizing clean to mask input/output declaration blunders.
• Hacking afterEvaluate to patch dependency graphs that should have been elegantly modeled with Provider.
• Injecting dynamic versions to sidestep dependency conflicts, thereby annihilating build reproducibility.
• Dumping the entire project's public configuration into a single, monolithic, bloated convention plugin.
• Accidentally enabling release-tier, heavy optimizations during default debug builds.
• Reading project state or global configuration directly within a task execution action.
• Forcing multiple distinct tasks to share a single temporary directory.
• Blindly restarting CI when cache hit rates plummet, rather than surgically analyzing the miss reason.
• Treating build scan URLs as optional trivia rather than hard evidence for performance regressions.
• Proclaiming that because "it ran successfully in the local IDE," the CI release pipeline is guaranteed to be safe.

Minimum Practical Scripts

./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath

This matrix of commands blankets the configuration phase, execution phase, caching, configuration caching, and dependency resolution. Any architectural mutation related to "Standalone Plugin Extensions" must be capable of explaining its behavioral impact using at least one of these commands.

References

• Gradle Developing Custom Plugins
• Gradle Testing Build Logic with TestKit
• Gradle Plugin Development Plugin