<!--
  ~ Copyright 2014 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.
  -->

<chapter id="javaGradle_plugin">
    <title>The Java Gradle Plugin Development Plugin</title>
    <note>
        <para>
            The Java Gradle plugin development plugin is currently <link linkend="feature_lifecycle">incubating</link>.
            Please be aware that the DSL and other configuration may change in later Gradle versions.
        </para>
    </note>

    <para>
        The Java Gradle Plugin development plugin can be used to assist in the development of Gradle plugins.  It automatically applies
        the <link linkend="java_plugin">Java</link> plugin, adds the <literal>gradleApi()</literal> dependency to the compile configuration
        and performs validation of plugin metadata during <literal>jar</literal> task execution.
    </para>
    <para>
        The plugin also integrates with <link linkend="test_kit">TestKit</link>, a library that aids in writing and executing functional
        tests for plugin code. It automatically adds the <literal>gradleTestKit()</literal> dependency to the test compile configuration
        and generates a plugin classpath manifest file consumed by a <literal>GradleRunner</literal> instance if found. Please refer to
        <xref linkend="sub:test-kit-automatic-classpath-injection"/> for more on its usage, configuration options and samples.
    </para>

    <section id="sec:gradle_plugin_dev_usage">
        <title>Usage</title>
        <para>To use the Java Gradle Plugin Development plugin, include the following in your build script:</para>
        <sample id="useJavaGradlePluginPlugin" dir="javaGradlePlugin" title="Using the Java Gradle Plugin Development plugin">
            <sourcefile file="build.gradle" snippet="use-java-gradle-plugin-plugin"/>
        </sample>
        <para>
            Applying the plugin automatically applies the <link linkend="java_plugin">Java</link> plugin and adds the
            <literal>gradleApi()</literal> dependency to the compile configuration.  It also adds some validations to the build.
        </para>
        <para>
            The following validations are performed:
        </para>
        <itemizedlist>
            <listitem>There is a plugin descriptor defined for the plugin.</listitem>
            <listitem>The plugin descriptor contains an <literal>implementation-class</literal> property.</listitem>
            <listitem>The <literal>implementation-class</literal> property references a valid class file in the jar.</listitem>
            <listitem>Each property getter or the corresponding field must be annotated with a property annotation like <literal>@InputFile</literal> and <literal>@OutputDirectory</literal>. Properties that don't participate in up-to-date checks should be annotated with <literal>@Internal</literal>.</listitem>
        </itemizedlist>
        <para>
            Any failed validations will result in a warning message.
        </para>
        <para>
            For each plugin you are developing, add an entry to the <code>gradlePlugin {}</code> script block:
        </para>
        <sample id="gradlePluginBlock" dir="javaGradlePlugin" title="Using the gradlePlugin {} block.">
            <sourcefile file="build.gradle" snippet="gradle-plugin-block" />
        </sample>
        <para>
            The <code>gradlePlugin {}</code> block defines the plugins being built by the project including the <code>id</code> and
            <code>implementationClass</code> of the plugin. From this data about the plugins being developed, Gradle
            can automatically:
        </para>
        <itemizedlist>
            <listitem>Generate the plugin descriptor in the <literal>jar</literal> file's <literal>META-INF</literal> directory.</listitem>
            <listitem>Configure the <link linkend="publishing_maven">Maven</link> or <link linkend="publishing_ivy">Ivy</link> publishing
                plugins to publish a <link linkend="sec:plugin_markers">Plugin Marker Artifact</link> for each plugin.</listitem>
        </itemizedlist>
    </section>
</chapter>
