Gradle Plugin Development Plugin

The Java Gradle Plugin development plugin can be used to assist in the development of Gradle plugins. It automatically applies the Java Library (java-library) plugin, adds the gradleApi() dependency to the compileOnlyApi configuration and performs validation of plugin metadata during jar task execution.

The plugin also integrates with TestKit, a library that aids in writing and executing functional tests for plugin code. It automatically adds the gradleTestKit() dependency to the testImplementation configuration and generates a plugin classpath manifest file consumed by a GradleRunner instance if found. Please refer to Automatic classpath injection with the Plugin Development Plugin for more on its usage, configuration options and samples.

Usage

To use the Java Gradle Plugin Development plugin, include the following in your build script:

build.gradle.kts

plugins {
    `java-gradle-plugin`
}

build.gradle

plugins {
    id 'java-gradle-plugin'
}

Applying the plugin automatically applies the Java Library(java-library) plugin and adds the gradleApi() dependency to the compileOnlyApi configuration. It also adds some validations to the build.

During jar task execution, the following plugin descriptor validations are performed, and any failure results in a warning message:

There is a plugin descriptor defined for the plugin.
The plugin descriptor contains an implementation-class property.
The implementation-class property references a valid class file in the jar.

Separately, the validatePlugins task validates the public API of the plugin’s task and artifact transform types:

Each property getter or the corresponding field must be annotated with a property annotation like @InputFile and @OutputDirectory. Properties that don’t participate in up-to-date checks should be annotated with @Internal.

For each plugin you are developing, register it into the gradlePlugin {} script block:

build.gradle.kts

gradlePlugin {
    plugins {
        register("org.gradle.sample.simple-plugin") {
            // id is automatically inferred as "org.gradle.sample.simple-plugin"
            implementationClass = "org.gradle.sample.SimplePlugin"
        }
        register("org.gradle.sample.convention-plugin") {
            // id is overwritten to "convention-plugin"
            id = "convention-plugin"
            implementationClass = "org.gradle.sample.ConventionPlugin"
        }
    }
}

build.gradle

gradlePlugin {
    plugins {
        register('org.gradle.sample.simple-plugin') {
            // id is automatically inferred as "org.gradle.sample.simple-plugin"
            implementationClass = 'org.gradle.sample.SimplePlugin'
        }
        register('org.gradle.sample.convention-plugin') {
            // id is overwritten to "convention-plugin"
            id = 'convention-plugin'
            implementationClass = 'org.gradle.sample.ConventionPlugin'
        }
    }
}

The gradlePlugin {} block defines the plugins being built by the project. The plugin id is set from the registration name, here org.gradle.sample.simple-plugin. Then, you define the implementationClass of the plugin, here org.gradle.sample.SimplePlugin.

You can override the plugin id by explicitly setting the id property such as id = "convention-plugin".

From this data about the plugins being developed, Gradle can automatically:

Generate the plugin descriptor in the jar file’s META-INF directory.
Configure the Plugin Marker Artifact publications (Maven or Ivy) for each plugin.
Publish each plugin to the Gradle Plugin Portal (see Publishing Plugins to Gradle Plugin Portal for details), but only if the Plugin Publishing Plugin has also been applied.

Tasks

The plugin adds the following tasks to the project:

pluginUnderTestMetadata — PluginUnderTestMetadata: Generates the metadata for plugin functional tests. The resulting plugin classpath manifest is consumed by a TestKit GradleRunner instance.
pluginDescriptors — GeneratePluginDescriptors: Generates plugin descriptors from the plugin declarations in the gradlePlugin {} block, written to the jar file’s META-INF/gradle-plugins directory.
validatePlugins — ValidatePlugins: Validates the plugin by checking the property annotations on the plugin’s task and artifact transform types.

Interactions

Some of the plugin’s behaviour depends on other, related plugins also being applied in your build, namely the Maven Publish (maven-publish) and Ivy Publish (ivy-publish) plugins.

Other plugins auto apply the Java Gradle Plugin, like the Plugin Publishing Plugin.

The automatic publication configuration described below is enabled by default. To opt out and define the publications yourself, set automatedPublishing = false in the gradlePlugin {} block; the plugin then creates no publications automatically.

Maven Publish Plugin

When the Java Gradle Plugin (java-gradle-plugin) detects that the Maven Publish Plugin (maven-publish) is also applied by the build, it will automatically configure the following MavenPublications:

a single "main" publication, named pluginMaven, based on the main Java component
multiple "marker" publications (one for each plugin defined in the gradlePlugin {} block), named <pluginName>PluginMarkerMaven (for example in the above example it would be simplePluginPluginMarkerMaven)

This automatic configuration happens in a Project.afterEvaluate() block (so at the end of the build configuration phase), and only if these publications haven’t already been defined, so it’s possible to create and customise them during the earlier stages of build configuration.

Ivy Publish Plugin

When the Java Gradle Plugin(java-gradle-plugin) detects that the Ivy Publish Plugin (ivy-publish) is also applied by the build, it will automatically configure the following IvyPublications:

a single "main" publication, named pluginIvy, based on the main Java component
multiple "marker" publications (one for each plugin defined in the gradlePlugin {} block), named <pluginName>PluginMarkerIvy (for example in the above example it would be simplePluginPluginMarkerIvy)

Plugin Publish Plugin

Starting from version 1.0.0, the Plugin Publish Plugin always auto-applies the Java Gradle Plugin (java-gradle-plugin) and the Maven Publish Plugin (maven-publish).