<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. It can deal with pure Java 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 pure
                <literal>javac</literal>. In particular as you would have to supply a groovy jar for doing this.
            </para>
        </footnote>
        with mixed Java and Groovy projects, and with pure Groovy projects.
    </para>

    <section>
        <title>Tasks</title>
        <para>The Groovy plugin does not add any tasks. It modifies some of the tasks of the Java Plugin.</para>
    </section>

    <section>
        <title>Project layout</title>
        <para>The Groovy plugin assumes the project layout shown in <xref linkend='groovylayout'/>. All the Groovy s
            ource directories can contain Groovy <emphasis>and</emphasis> Java code. The Java source directories may
            only contain Java source code (and can of course be empty).
            <footnote>
                <para>We are using the same conventions as introduced by Russel Winders Gant tool (<ulink
                        url='http://gant.codehaus.org'/>).
                </para>
            </footnote>
        </para>

        <table id='groovylayout'>
            <title>Groovy plugin - project layout</title>
            <thead>
                <tr>
                    <td>Directory</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>src/main/groovy</filename>
                </td>
                <td>Application/Library Groovy/Java source</td>
            </tr>
            <tr>
                <td>
                    <filename>src/test/groovy</filename>
                </td>
                <td>Test Groovy/Java source</td>
            </tr>
        </table>
    </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 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 adds the convention properties shown in <xref linkend='groovyconvention'/>
        and <xref linkend='groovyconventionFloatingDir'/>.</para>

        <table id='groovyconvention'>
            <title>Groovy plugin - directory properties</title>
            <thead>
                <tr>
                    <td>Dir Name</td>
                    <td>Dir File</td>
                    <td>Default Value Name</td>
                    <td>Default Value File</td>
                </tr>
            </thead>
            <tr>
                <td>groovySrcDirNames</td>
                <td>groovySrcDirs</td>
                <td>
                    [<literal>main/groovy</literal>]
                </td>
                <td>
                    [<literal><replaceable>srcRoot</replaceable>/main/groovy</literal>]
                </td>
            </tr>
            <tr>
                <td>groovyTestSrcDirNames</td>
                <td>groovyTestSrcDirs</td>
                <td>
                    <literal>test/groovy</literal>
                </td>
                <td>
                    [<literal><replaceable>srcRoot</replaceable>/test/groovy</literal>]
                </td>
            </tr>
            <tr>
                <td>groovydocDirName</td>
                <td>groovydocDir</td>
                <td>
                    <literal>groovydoc</literal>
                </td>
                <td>
                    <literal><replaceable>docsDir</replaceable>/groovydoc</literal>
                </td>
            </tr>

        </table>
        <table id='groovyconventionFloatingDir'>
            <title>Groovy Plugin - floating directory properties</title>
            <thead>
                <tr>
                    <td>Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>floatingGroovySrcDirs</td>
                <td>List</td>
                <td>empty</td>
            </tr>
            <tr>
                <td>floatingGroovyTestSrcDirs</td>
                <td>List</td>
                <td>empty</td>
            </tr>
        </table>
    </section>

    <section id='sec:groovyCompile'>
        <title>Compile</title>
        <para>The
            <emphasis>GroovyCompile</emphasis>
            task has two instances,
            <literal>compile</literal>
            and <literal>compileTests</literal>. The task type extends the
            <literal>Compile</literal>
            task (see <xref linkend='sec:compile'/>)
        </para>
        <table>
            <title>Groovy Convention Object - source directory properties</title>
            <thead>
                <tr>
                    <td>Task Instance</td>
                    <td>Task Property</td>
                    <td>Convention Property</td>
                </tr>
            </thead>
            <tr>
                <td>compile</td>
                <td>groovySourceDirs</td>
                <td>groovySrcDirs</td>
            </tr>
            <tr>
                <td>compileTests</td>
                <td>groovySourceDirs</td>
                <td>groovyTestSrcDirs</td>
            </tr>

        </table>
        <para>Have a look at <apilink class='org.gradle.api.tasks.compile.GroovyCompile'/>
            to learn about the details. 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>
    </section>
    <section id='sec:test'>
        <title>Test</title>
        <para>In contrast to the Java plugin the fork mode is set to once by default, because of the significant startup
            time of Groovy. The Java plugin uses per test as fork mode (see <xref linkend='sec:java_test'/>).
        </para>
    </section>
</chapter>
