# Gradle Plugin Development Plugin

version 9.8.0-milestone-2

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

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