<!--
  ~ Copyright 2009 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='groovy_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Groovy Plugin</title>
    <para>The Groovy plugin extends the Java plugin to add support for Groovy projects. It can deal with Groovy-only projects and
        with mixed Java/Groovy projects. It can even deal with Java-only projects.
        <footnote>
            <para>We don't recommend this, as the Groovy plugin uses the <emphasis>Groovyc</emphasis>
                Ant task to compile the sources. For pure Java projects you might rather stick with
                <literal>javac</literal>. In particular as you would have to supply a groovy jar for doing this.
            </para>
        </footnote>
        The Groovy plugin supports joint compilation of Java and Groovy. This means that your project can contain Groovy
        classes which use Java classes, and vice versa.
    </para>

    <section>
        <title>Usage</title>
        <para>To use the Groovy plugin, include in your build script:</para>
        <sample id="useGroovyPlugin" dir="groovy/quickstart" title="Using the Groovy plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>

    <section>
        <title>Tasks</title>
        <para>The Groovy plugin adds the following tasks to the project.</para>
        <table>
            <title>Groovy plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td><literal>compileGroovy</literal></td>
                <td><literal>compileJava</literal></td>
                <td><apilink class="org.gradle.api.tasks.compile.GroovyCompile"/></td>
                <td>Compiles production Groovy source files using groovyc.</td>
            </tr>
            <tr>
                <td><literal>compileTestGroovy</literal></td>
                <td><literal>compileTestJava</literal></td>
                <td><apilink class="org.gradle.api.tasks.compile.GroovyCompile"/></td>
                <td>Compiles test Groovy source files using groovyc.</td>
            </tr>
            <tr>
                <td><literal>compile<replaceable>SourceSet</replaceable>Groovy</literal></td>
                <td><literal>compile<replaceable>SourceSet</replaceable>Java</literal></td>
                <td><apilink class="org.gradle.api.tasks.compile.GroovyCompile"/></td>
                <td>Compiles the given source set's Groovy source files using groovyc.</td>
            </tr>
            <tr>
                <td><literal>groovydoc</literal></td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.javadoc.Groovydoc"/></td>
                <td>Generates API documentation for the production Groovy source files using groovydoc.</td>
            </tr>
        </table>
        <para>The Groovy plugin adds the following dependencies to tasks added by the Java plugin.</para>
        <table>
            <title>Groovy plugin - additional task dependencies</title>
            <thead>
                <td>Task name</td>
                <td>Depends on</td>
            </thead>
            <tr>
                <td>classes</td>
                <td>compileGroovy</td>
            </tr>
            <tr>
                <td>testClasses</td>
                <td>compileTestGroovy</td>
            </tr>
            <tr>
                <td><replaceable>sourceSet</replaceable>Classes</td>
                <td>compile<replaceable>SourceSet</replaceable>Groovy</td>
            </tr>
        </table>
        <figure>
            <title>Groovy plugin - tasks</title>
            <imageobject>
                <imagedata fileref="img/groovyPluginTasks.png"/>
            </imageobject>
        </figure>
    </section>

    <section>
        <title>Project layout</title>
        <para>The Groovy plugin assumes the project layout shown in <xref linkend='groovylayout'/>. All the Groovy
            source directories can contain Groovy <emphasis>and</emphasis> Java code. The Java source directories may
            only contain Java source code.
            <footnote>
                <para>We are using the same conventions as introduced by Russel Winders Gant tool (<ulink
                        url='http://gant.codehaus.org'/>).
                </para>
            </footnote>
            None of these directories need exist or have anything in them. The Groovy plugin will compile whatever it
            finds, and handles anything which is missing.
        </para>

        <table id='groovylayout'>
            <title>Groovy plugin - project layout</title>
            <thead>
                <tr>
                    <td>Directory</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <xi:include href="javaProjectMainLayout.xml"/>
            <tr>
                <td>
                    <filename>src/main/groovy</filename>
                </td>
                <td>Production Groovy source. May also contain Java source for joint compilation.</td>
            </tr>
            <xi:include href="javaProjectTestLayout.xml"/>
            <tr>
                <td>
                    <filename>src/test/groovy</filename>
                </td>
                <td>Test Groovy source. May also contain Java source for joint compilation.</td>
            </tr>
            <xi:include href="javaProjectGenericLayout.xml"/>
            <tr>
                <td>
                    <filename>src/<replaceable>sourceSet</replaceable>/groovy</filename>
                </td>
                <td>Groovy source for the given source set. May also contain Java source for joint compilation.</td>
            </tr>
        </table>

        <section>
            <title>Changing the project layout</title>
            <para>TBD</para>
            <sample id="customGroovySourceLayout" dir="groovy/customizedLayout" title="Custom Groovy source layout">
                <sourcefile file="build.gradle" snippet="define-main"/>
            </sample>
        </section>
        
    </section>

    <section>
        <title>Dependency management</title>
        <para>The Groovy plugin adds a dependency configuration called <literal>groovy</literal>.</para>
        <para>Gradle is written in Groovy and allows you to write your build scripts in Groovy. But this is an internal
            aspect of Gradle which is strictly separated from building Groovy projects. You are free to choose the Groovy
            version your project should be build with. This Groovy version is not just used for compiling your code and
            running your tests. The <literal>groovyc</literal> compiler and the <literal>groovydoc</literal>
            tool are also taken from the Groovy version you provide. As usual, with freedom comes responsibility ;). You are
            not just free to choose a Groovy version, you have to provide one. Gradle expects that the groovy libraries are
            assigned to the <literal>groovy</literal> dependency configuration. Here is an example using the public Maven
            repository:
        </para>
        <sample id="quickstartGroovyDependency" dir="groovy/quickstart" title="Configuration of Groovy plugin">
            <sourcefile file="build.gradle" snippet="groovy-dependency"/>
        </sample>
        <para>And here is an example using the Groovy JARs checked into the <filename>lib</filename> directory of the source
            tree:</para>
        <sample id="flatDirGroovyDependency" dir="userguide/tutorial/groovyWithFlatDir" title="Configuration of Groovy plugin">
            <sourcefile file="build.gradle" snippet="groovy-dependency"/>
        </sample>
    </section>

    <section>
        <title>Convention properties</title>
        <para>The Groovy plugin does not add any convention properties to the project.</para>
    </section>

    <section>
        <title>Source set properties</title>
        <para>The Groovy plugin adds the following convention properties to each source set in the project. You can
            use these properties in your build script as though they were properties of the source set object (see
            <xref linkend="sub:more_about_convention_objects"/>).</para>
        <table>
            <title>Groovy plugin - source set properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>groovy</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.file.SourceDirectorySet"/> (read-only)
                </td>
                <td>
                    Not null
                </td>
                <td>
                    The Groovy source files of this source set. Contains all <filename>.groovy</filename> and
                    <filename>.java</filename> files found in the Groovy source directories, and excludes all other
                    types of files.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>groovy.srcDirs</literal>
                </td>
                <td>
                    <classname>Set&lt;File></classname>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.
                </td>
                <td>
                    <literal>[<replaceable>projectDir</replaceable>/src/<replaceable>name</replaceable>/groovy]</literal>
                </td>
                <td>
                    The source directories containing the Groovy source files of this source set. May also contain
                    Java source files for joint compilation.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>allGroovy</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.file.FileTree"/> (read-only)
                </td>
                <td>
                    Not null
                </td>
                <td>
                    All Groovy source files of this source set. Contains only the <filename>.groovy</filename> files
                    found in the Groovy source directories.
                </td>
            </tr>
        </table>
        <para>These properties are provided by a convention object of type <apilink class="org.gradle.api.tasks.GroovySourceSet"/>.</para>
        <para>The Groovy plugin also modifies some source set properties:</para>
        <table>
            <title>Groovy plugin - source set properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Change</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>allJava</literal>
                </td>
                <td>Adds all <filename>.java</filename> files found in the Groovy source directories.</td>
            </tr>
            <tr>
                <td>
                    <literal>allSource</literal>
                </td>
                <td>Adds all source files found in the Groovy source directories.</td>
            </tr>
        </table>

    </section>

    <section id='sec:groovyCompile'>
        <title>CompileGroovy</title>
        <para>The Groovy plugin adds a <apilink class="org.gradle.api.tasks.compile.GroovyCompile"/> instance for
            each source set in the project. The task type extends the <literal>Compile</literal>
            task (see <xref linkend='sec:compile'/>). The compile task delegates to the Ant Groovyc task to do the
            compile. Via the compile task you can set most of the properties of Ants Groovyc task.
        </para>
        <table>
            <title>Groovy plugin - CompileGroovy properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>classpath</literal>
                </td>
                <td><apilink class="org.gradle.api.file.FileCollection"/></td>
                <td><literal><replaceable>sourceSet</replaceable>.compileClasspath</literal></td>
            </tr>
            <tr>
                <td>
                    <literal>source</literal>
                </td>
                <td><apilink class="org.gradle.api.file.FileTree"/>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.</td>
                <td><literal><replaceable>sourceSet</replaceable>.groovy</literal></td>
            </tr>
            <tr>
                <td>
                    <literal>destinationDir</literal>
                </td>
                <td><classname>File</classname>.</td>
                <td><literal><replaceable>sourceSet</replaceable>.output.classesDir</literal></td>
            </tr>
            <tr>
                <td>
                    <literal>groovyClasspath</literal>
                </td>
                <td><apilink class="org.gradle.api.file.FileCollection"/></td>
                <td><literal>groovy</literal> configuration</td>
            </tr>
        </table>
    </section>
</chapter>
