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

[[javaGradle_plugin]]
== The Java Gradle Plugin Development Plugin


[NOTE]
====
 
The Java Gradle plugin development plugin is currently <<feature_lifecycle,incubating>>. Please be aware that the DSL and other configuration may change in later Gradle versions.
 
====

The Java Gradle Plugin development plugin can be used to assist in the development of Gradle plugins. It automatically applies the <<java_plugin,Java>> plugin, adds the `gradleApi()` dependency to the compile configuration and performs validation of plugin metadata during `jar` task execution.

The plugin also integrates with <<test_kit,TestKit>>, a library that aids in writing and executing functional tests for plugin code. It automatically adds the `gradleTestKit()` dependency to the test compile configuration and generates a plugin classpath manifest file consumed by a `GradleRunner` instance if found. Please refer to <<sub:test-kit-automatic-classpath-injection>> 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:

++++
<sample id="useJavaGradlePluginPlugin" dir="javaGradlePlugin" title="Using the Java Gradle Plugin Development plugin">
            <sourcefile file="build.gradle" snippet="use-java-gradle-plugin-plugin"/>
        </sample>
++++

Applying the plugin automatically applies the <<java_plugin,Java>> plugin and adds the `gradleApi()` dependency to the compile 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:

++++
<sample id="gradlePluginBlock" dir="javaGradlePlugin" title="Using the gradlePlugin {} block.">
            <sourcefile file="build.gradle" snippet="gradle-plugin-block"/>
        </sample>
++++

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,Maven>> or <<publishing_ivy,Ivy>> publishing plugins to publish a <<sec:plugin_markers,Plugin Marker Artifact>> for each plugin.
