# Implementing Pre-compiled Script Plugins

version 9.1.0-20250909012757+0000

A precompiled script plugin is typically a Kotlin script that has been compiled and distributed as Java class files packaged in a library. These scripts are intended to be consumed as binary Gradle plugins and are recommended for use as convention plugins.

A convention plugin is a plugin that normally configures existing core and community plugins with your own conventions (i.e. default values) such as setting the Java version by using `java.toolchain.languageVersion = JavaLanguageVersion.of(17)`. Convention plugins are also used to enforce project standards and help streamline the build process. They can apply and configure plugins, create new tasks and extensions, set dependencies, and much more.

## Setting the plugin ID

The plugin ID for a precompiled script is derived from its file name and optional package declaration.

For example, a script named `code-quality.gradle(.kts)` located in `src/main/groovy` (or `src/main/kotlin`) without a package declaration would be exposed as the `code-quality` plugin:

buildSrc/build.gradle.kts

    plugins {
        `kotlin-dsl`
    }

app/build.gradle.kts

    plugins {
        id("code-quality")
    }

buildSrc/build.gradle

    plugins {
        id 'groovy-gradle-plugin'
    }

app/build.gradle

    plugins {
        id 'code-quality'
    }

On the other hand, a script named `code-quality.gradle.kts` located in `src/main/kotlin/my` with the package declaration `my` would be exposed as the `my.code-quality` plugin:

buildSrc/build.gradle.kts

    plugins {
        `kotlin-dsl`
    }

app/build.gradle.kts

    plugins {
        id("my.code-quality")
    }

When creating precompiled script plugins intended for `Settings` or `Init` scripts, the filename suffix determines where Gradle applies them:

- `.settings.gradle` or `.settings.gradle.kts` → interpreted as `Plugin<Settings>`

- `.init.gradle` or `.init.gradle.kts` → interpreted as `Plugin<Init>`

- `.gradle` or `.gradle.kts` → interpreted as the default `Plugin<Project>`

| Groovy pre-compiled script plugins cannot have packages.

## Making a plugin configurable using extensions

Extension objects are commonly used in plugins to expose configuration options and additional functionality to build scripts.

When you apply a plugin that defines an extension, you can access the extension object and configure its properties or call its methods to customize the behavior of the plugin or tasks provided by the plugin.

A Project has an associated ExtensionContainer object that contains all the settings and properties for the plugins that have been applied to the project. You can provide configuration for your plugin by adding an extension object to this container.

Let’s update our `greetings` example:

buildSrc/src/main/kotlin/greetings.gradle.kts

    // Create extension object
    interface GreetingPluginExtension {
        val message: Property<String>
    }

    // Add the 'greeting' extension object to project
    val extension = project.extensions.create<GreetingPluginExtension>("greeting")

buildSrc/src/main/groovy/greetings.gradle

    // Create extension object
    interface GreetingPluginExtension {
        Property<String> getMessage()
    }

    // Add the 'greeting' extension object to project
    def extension = project.extensions.create("greeting", GreetingPluginExtension)

You can set the value of the `message` property directly with `extension.message.set("Hi from Gradle,")`.

However, the `GreetingPluginExtension` object becomes available as a project property with the same name as the extension object. You can now access `message` like so:

buildSrc/src/main/kotlin/greetings.gradle.kts

    // Where the<GreetingPluginExtension>() is equivalent to project.extensions.getByType(GreetingPluginExtension::class.java)
    the<GreetingPluginExtension>().message.set("Hi from Gradle")

buildSrc/src/main/groovy/greetings.gradle

    extensions.findByType(GreetingPluginExtension).message.set("Hi from Gradle")

If you apply the `greetings` plugin, you can set the convention in your build script:

app/build.gradle.kts

    plugins {
        application
        id("greetings")
    }

    greeting {
        message = "Hello from Gradle"
    }

app/build.gradle

    plugins {
        id 'application'
        id('greetings')
    }

    configure(greeting) {
        message = "Hello from Gradle"
    }

## Adding default configuration as conventions

In plugins, you can define default values, also known as conventions, using the `project` object.

Convention properties are properties that are initialized with default values but can be overridden:

buildSrc/src/main/kotlin/greetings.gradle.kts

    // Create extension object
    interface GreetingPluginExtension {
        val message: Property<String>
    }

    // Add the 'greeting' extension object to project
    val extension = project.extensions.create<GreetingPluginExtension>("greeting")

    // Set a default value for 'message'
    extension.message.convention("Hello from Gradle")

buildSrc/src/main/groovy/greetings.gradle

    // Create extension object
    interface GreetingPluginExtension {
        Property<String> getMessage()
    }

    // Add the 'greeting' extension object to project
    def extension = project.extensions.create("greeting", GreetingPluginExtension)

    // Set a default value for 'message'
    extension.message.convention("Hello from Gradle")

`extension.message.convention(…​)` sets a convention for the `message` property of the extension. This convention specifies that the value of `message` should default to `"Hello from Gradle"`.

If the `message` property is not explicitly set, its value will be automatically set to `"Hello from Gradle"`.

## Mapping extension properties to task properties

Using an extension and mapping it to a custom task’s input/output properties is common in plugins.

In this example, the message property of the `GreetingPluginExtension` is mapped to the message property of the `GreetingTask` as an input:

buildSrc/src/main/kotlin/greetings.gradle.kts

    // Create extension object
    interface GreetingPluginExtension {
        val message: Property<String>
    }

    // Add the 'greeting' extension object to project
    val extension = project.extensions.create<GreetingPluginExtension>("greeting")

    // Set a default value for 'message'
    extension.message.convention("Hello from Gradle")

    // Create a greeting task
    abstract class GreetingTask : DefaultTask() {
        @Input
        val message = project.objects.property<String>()

        @TaskAction
        fun greet() {
            println("Message: ${message.get()}")
        }
    }

    // Register the task and set the convention
    tasks.register<GreetingTask>("hello") {
        message.convention(extension.message)
    }

buildSrc/src/main/groovy/greetings.gradle

    // Create extension object
    interface GreetingPluginExtension {
        Property<String> getMessage()
    }

    // Add the 'greeting' extension object to project
    def extension = project.extensions.create("greeting", GreetingPluginExtension)

    // Set a default value for 'message'
    extension.message.convention("Hello from Gradle")

    // Create a greeting task
    abstract class GreetingTask extends DefaultTask {
        @Input
        abstract Property<String> getMessage()

        @TaskAction
        void greet() {
            println("Message: ${message.get()}")
        }
    }

    // Register the task and set the convention
    tasks.register("hello", GreetingTask) {
        message.convention(extension.message)
    }

    $ gradle -q hello
    Message: Hello from Gradle

This means that changes to the extension’s `message` property will trigger the task to be considered out-of-date, ensuring that the task is re-executed with the new message.

You can find out more about types that you can use in task implementations and extensions in Lazy Configuration.

## Applying external plugins

In order to apply an external plugin in a precompiled script plugin, it has to be added to the plugin project’s implementation classpath in the plugin’s build file:

buildSrc/build.gradle.kts

    plugins {
        `kotlin-dsl`
    }

    repositories {
        mavenCentral()
    }

    dependencies {
        implementation("com.bmuschko:gradle-docker-plugin:6.4.0")
    }

buildSrc/build.gradle

    plugins {
        id 'groovy-gradle-plugin'
    }

    repositories {
        mavenCentral()
    }

    dependencies {
        implementation 'com.bmuschko:gradle-docker-plugin:6.4.0'
    }

It can then be applied in the precompiled script plugin:

buildSrc/src/main/kotlin/my-plugin.gradle.kts

    plugins {
        id("com.bmuschko.docker-remote-api")
    }

buildSrc/src/main/groovy/my-plugin.gradle

    plugins {
        id 'com.bmuschko.docker-remote-api'
    }

The plugin version in this case is defined in the dependency declaration.