// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[java_gradle_plugin]]
= 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_plugin.adoc#java_library_plugin,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 <<test_kit.adoc#test_kit,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 <<test_kit.adoc#sub:test-kit-automatic-classpath-injection,Automatic classpath injection with the Plugin Development Plugin>> for more on its usage, configuration options and samples.


[[sec:gradle_plugin_dev_usage]]
== Usage

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

.Using the Java Gradle Plugin Development plugin
====
include::sample[dir="snippets/java/javaGradlePlugin/groovy",files="build.gradle[tags=use-java-gradle-plugin-plugin]"]
include::sample[dir="snippets/java/javaGradlePlugin/kotlin",files="build.gradle.kts[tags=use-java-gradle-plugin-plugin]"]
====

Applying the plugin automatically applies the <<java_library_plugin.adoc#java_library_plugin,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:

.Using the gradlePlugin {} block.
====
include::sample[dir="snippets/java/javaGradlePlugin/groovy",files="build.gradle[tags=gradle-plugin-block]"]
include::sample[dir="snippets/java/javaGradlePlugin/kotlin",files="build.gradle.kts[tags=gradle-plugin-block]"]
====

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:

* Generate the plugin descriptor in the `jar` file's `META-INF` directory.
* Configure the <<publishing_maven.adoc#publishing_maven,Maven>> or <<publishing_ivy.adoc#publishing_ivy,Ivy Publish Plugins>> publishing plugins to publish a <<plugins.adoc#sec:plugin_markers,Plugin Marker Artifact>> for each plugin.
* Moreover, if the link:https://plugins.gradle.org/docs/publish-plugin[Plugin Publishing Plugin] is applied, it will publish each plugin using the same name, plugin id, display name, and description to the Gradle Plugin Portal (see <<publishing_gradle_plugins.adoc#publishing_portal,Publishing Plugins to Gradle Plugin Portal>> for details).
