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 api 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 api configuration. It also adds some validations to the build.

The following validations are performed:

  • 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.

  • 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.

Any failed validations will result in a warning message.

For each plugin you are developing, add an entry to the gradlePlugin {} script block:

build.gradle.kts
gradlePlugin {
    plugins {
        create("simplePlugin") {
            id = "org.gradle.sample.simple-plugin"
            implementationClass = "org.gradle.sample.SimplePlugin"
        }
    }
}
build.gradle
gradlePlugin {
    plugins {
        simplePlugin {
            id = 'org.gradle.sample.simple-plugin'
            implementationClass = 'org.gradle.sample.SimplePlugin'
        }
    }
}

The gradlePlugin {} block defines the plugins being built by the project including the id and implementationClass of the plugin. From this data about the plugins being developed, Gradle can automatically:

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.

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)

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.

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).