<!--
  ~ 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 code, mixed Groovy and Java code, and even pure Java code (although we don't necessarily recommend to use it for the latter).
        The plugin supports <emphasis>joint compilation</emphasis>, which allows to freely mix and match Groovy and Java code,
        with dependencies in both directions. For example, a Groovy class can extend a Java class that in turn extends a Groovy class.
        This makes it possible to use the best language for the job, and to rewrite any class in the other language if needed.
    </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.</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.</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.</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.</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 Winder's Gant tool (<ulink
                        url='http://gant.codehaus.org'/>).
                </para>
            </footnote>
            None of these directories need to exist or have anything in them; the Groovy plugin will simply compile
            whatever it finds.
        </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 sources. May also contain Java sources for joint compilation.</td>
            </tr>
            <xi:include href="javaProjectTestLayout.xml"/>
            <tr>
                <td>
                    <filename>src/test/groovy</filename>
                </td>
                <td>Test Groovy sources. May also contain Java sources for joint compilation.</td>
            </tr>
            <xi:include href="javaProjectGenericLayout.xml"/>
            <tr>
                <td>
                    <filename>src/<replaceable>sourceSet</replaceable>/groovy</filename>
                </td>
                <td>Groovy sources for the given source set. May also contain Java sources for joint compilation.</td>
            </tr>
        </table>

        <section>
            <title>Changing the project layout</title>
            <para>Just like the Java plugin, the Groovy plugin allows to configure custom locations for Groovy production and test sources.</para>
            <sample id="customGroovySourceLayout" dir="groovy/customizedLayout" title="Custom Groovy source layout">
                <sourcefile file="build.gradle" snippet="custom-source-locations"/>
            </sample>
        </section>
        
    </section>

    <section>
        <title>Dependency management</title>
        <para>Because Gradle itself is partly implemented in Groovy, and its build language is also based on Groovy, Gradle already ships
            with a Groovy library (1.8.6 as of Gradle 1.3). Nevertheless, Groovy projects need to explicitly add a Groovy dependency to
            the appropriate configuration(s). This dependency, which can be the same or a different Groovy version than the one used internally by Gradle,
            will then be used as a compile and runtime dependency for the project's Groovy code. It will also be used to execute the Groovy
            compiler and Groovydoc tool, respectively.
            <footnote>
                More precisely, if a <literal>GroovyCompile</literal> or <literal>Groovydoc</literal> task's <literal>groovyClasspath</literal>
                is empty, the plugin searches the task's <literal>classpath</literal> for a
                <literal>groovy-all(-indy)</literal> or <literal>groovy(-indy)</literal> artifact. If it finds the former, it adds the same artifact
                to <literal>groovyClasspath</literal>. If it finds the latter, and the project has at least one repository declared, the plugin adds
                a corresponding repository dependency to <literal>groovyClasspath</literal>.
            </footnote>
        </para>
        <para>
            If Groovy is used both for production code, the Groovy dependency should be added to the <literal>compile</literal>
            configuration:
        </para>
        <sample id="quickstartGroovyDependency" dir="groovy/quickstart" title="Configuration of Groovy dependency">
            <sourcefile file="build.gradle" snippet="groovy-dependency"/>
        </sample>
        <para>
            If Groovy is only used for test code, the Groovy dependency should be added to the <literal>testCompile</literal>
            (but not the <literal>compile</literal>) configuration:
        </para>
        <sample id="groovyTestDependency" dir="userguide/groovy/groovyDependency" title="Configuration of Groovy test dependency">
            <sourcefile file="build.gradle" snippet="groovy-test-dependency"/>
        </sample>
        <para>
            To use the same Groovy library that ships with Gradle, declare a <literal>localGroovy()</literal> dependency. Note that
            different Gradle versions ship with different Groovy versions; as such, using <literal>localGroovy()</literal> is less
            safe then explicitly choosing a Groovy version.
        </para>
        <sample id="bundledGroovyDependency" dir="userguide/groovy/groovyDependency" title="Configuration of bundled Groovy dependency">
            <sourcefile file="build.gradle" snippet="bundled-groovy-dependency"/>
        </sample>
        <para>
            In earlier Gradle versions, the Groovy dependency was instead added to the <literal>groovy</literal> configuration.
            This is no longer the preferred approach, but is still supported for backwards compatibility.
        </para>
        <sample id="groovyConfiguration" dir="userguide/groovy/groovyDependency" title="Configuration of Groovy configuration">
            <sourcefile file="build.gradle" snippet="groovy-configuration"/>
        </sample>
        <para>The Groovy library doesn't necessarily have to come from a remote repository. It could also come from a local
            <literal>lib</literal> directory, perhaps checked in to source control:</para>
        <sample id="groovyFileDependency" dir="userguide/tutorial/groovyWithFlatDir" title="Configuration of Groovy file dependency">
            <sourcefile file="build.gradle" snippet="groovy-dependency"/>
        </sample>

    </section>

    <section>
        <title>Adding custom GroovyCompile and Groovydoc tasks</title>
        <para>
            When adding custom <literal>GroovyCompile</literal> and <literal>Groovydoc</literal> tasks, it's important to understand
            that these tasks consume Groovy in two ways: on their <literal>classpath</literal>, and on their <literal>groovyClasspath</literal>.
            The former is the regular class path required by these tools to locate referenced classes, and will typically contain more than
            just the Groovy library. The latter is used to load the Groovy compiler and Groovydoc tool, respectively, and shouldn't contain anything
            other than the Groovy library and its dependencies.
        </para>
        <para>
            Unless <literal>groovyClasspath</literal> is explicitly configured for a task, the Groovy (base) plugin will try to infer
            the Groovy library to be used from the task's<literal>classpath</literal>. For example, if <literal>classpath</literal> contains
            <literal>groovy-all-2.0.5.jar</literal>, the plugin will add the same dependency to <literal>groovyClasspath</literal>. If the project
            has at least one repository defined, an external dependency will be added (e.g. <literal>"org.codehaus.groovy:groovy-all:2.0.5"</literal>);
            otherwise, a file dependency will be added.
        </para>
        <para>
            Note: When using the <literal>groovy</literal> rather than the <literal>groovy-all</literal> artifact, automatic configuration of
            <literal>groovyClasspath</literal> will only work correctly if the project declares a repository that contains the <literal>groovy</literal>
            artifact along with a descriptor (<literal>pom.xml</literal> or <literal>ivy.xml</literal>) listing its dependencies. Otherwise, only the
            artifact itself will be added to <literal>groovyClasspath</literal>, which will likely result in a <literal>NoClassDefFoundError</literal>
            during compilation.
        </para>
    </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>GroovyCompile</title>
        <para>The Groovy plugin adds a <apilink class="org.gradle.api.tasks.compile.GroovyCompile"/> task for
            each source set in the project. The task type extends the <literal>JavaCompile</literal>
            task (see <xref linkend='sec:compile'/>). Unless <literal>groovyOptions.useAnt</literal> is set to <literal>true</literal>,
            Gradle's native Groovy compiler integration is used. For most projects, this is the better choice than the Ant-based compiler.
            The <literal>GroovyCompile</literal> task supports most configuration options of the official Groovy compiler.
        </para>
        <table>
            <title>Groovy plugin - GroovyCompile 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 if non-empty; Groovy library found on <literal>classpath</literal> otherwise</td>
            </tr>
        </table>
    </section>
</chapter>
