# Chapter 24. The Groovy Plugin

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 joint compilation, 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.

## 24.1. Usage

To use the Groovy plugin, include in your build script:

Example 24.1. Using the Groovy plugin

`build.gradle`

    apply plugin: 'groovy'

## 24.2. Tasks

The Groovy plugin adds the following tasks to the project.

Table 24.1. Groovy plugin - tasks

Task name | Depends on | Type | Description
`compileGroovy` | `compileJava` | `GroovyCompile` | Compiles production Groovy source files.
`compileTestGroovy` | `compileTestJava` | `GroovyCompile` | Compiles test Groovy source files.
`compile`SourceSet`Groovy` | `compile`SourceSet`Java` | `GroovyCompile` | Compiles the given source set's Groovy source files.
`groovydoc` | - | `Groovydoc` | Generates API documentation for the production Groovy source files.

The Groovy plugin adds the following dependencies to tasks added by the Java plugin.

Table 24.2. Groovy plugin - additional task dependencies

Task name | Depends on
classes | compileGroovy
testClasses | compileTestGroovy
`sourceSet`Classes | compile`SourceSet`Groovy

Figure 24.1. Groovy plugin - tasks

## 24.3. Project layout

The Groovy plugin assumes the project layout shown in Table 24.3, “Groovy plugin - project layout”. All the Groovy source directories can contain Groovy and Java code. The Java source directories may only contain Java source code. [11] None of these directories need to exist or have anything in them; the Groovy plugin will simply compile whatever it finds.

Table 24.3. Groovy plugin - project layout

Directory | Meaning
`src/main/java` | Production Java source
`src/main/resources` | Production resources
`src/main/groovy` | Production Groovy sources. May also contain Java sources for joint compilation.
`src/test/java` | Test Java source
`src/test/resources` | Test resources
`src/test/groovy` | Test Groovy sources. May also contain Java sources for joint compilation.
`src/`sourceSet`/java` | Java source for the given source set
`src/`sourceSet`/resources` | Resources for the given source set
`src/`sourceSet`/groovy` | Groovy sources for the given source set. May also contain Java sources for joint compilation.

### 24.3.1. Changing the project layout

Just like the Java plugin, the Groovy plugin allows to configure custom locations for Groovy production and test sources.

Example 24.2. Custom Groovy source layout

`build.gradle`

    sourceSets {
        main {
            groovy {
                srcDirs = ['src/groovy']
            }
        }

        test {
            groovy {
                srcDirs = ['test/groovy']
            }
        }
    }

## 24.4. Dependency management

Because Gradle's build language is based on Groovy, and parts of Gradle are implemented in Groovy, Gradle already ships with a Groovy library (1.8.6 as of Gradle 1.6). Nevertheless, Groovy projects need to explicitly declare a Groovy dependency. This dependency will then be used on compile and runtime class paths. It will also be used to get hold of the Groovy compiler and Groovydoc tool, respectively.

If Groovy is used for production code, the Groovy dependency should be added to the `compile` configuration:

Example 24.3. Configuration of Groovy dependency

`build.gradle`

    repositories {
        mavenCentral()
    }

    dependencies {
        compile 'org.codehaus.groovy:groovy-all:2.2.0'
    }

If Groovy is only used for test code, the Groovy dependency should be added to the `testCompile` configuration:

Example 24.4. Configuration of Groovy test dependency

`build.gradle`

    dependencies {
        testCompile "org.codehaus.groovy:groovy-all:2.2.0"
    }

To use the Groovy library that ships with Gradle, declare a `localGroovy()` dependency. Note that different Gradle versions ship with different Groovy versions; as such, using `localGroovy()` is less safe then declaring a regular Groovy dependency.

Example 24.5. Configuration of bundled Groovy dependency

`build.gradle`

    dependencies {
        compile localGroovy()
    }

The Groovy library doesn't necessarily have to come from a remote repository. It could also come from a local `lib` directory, perhaps checked in to source control:

Example 24.6. Configuration of Groovy file dependency

`build.gradle`

    repositories {
        flatDir { dirs 'lib' }
    }

    dependencies {
        compile module('org.codehaus.groovy:groovy:1.6.0') {
            dependency('asm:asm-all:2.2.3')
            dependency('antlr:antlr:2.7.7')
            dependency('commons-cli:commons-cli:1.2')
            module('org.apache.ant:ant:1.7.0') {
                dependencies('org.apache.ant:ant-junit:1.7.0@jar', 'org.apache.ant:ant-launcher:1.7.0')
            }
        }
    }

## 24.5. Automatic configuration of groovyClasspath

`GroovyCompile` and `Groovydoc` tasks consume Groovy in two ways: on their `classpath`, and on their `groovyClasspath`. The former is used to locate classes referenced by the source code, and will typically contain the Groovy library along with other libraries. The latter is used to load and execute the Groovy compiler and Groovydoc tool, respectively, and should only contain the Groovy library and its dependencies.

Unless a task's `groovyClasspath` is configured explicitly, the Groovy (base) plugin will try to infer it from the task's `classpath`. This is done as follows:

- If a `groovy-all(-indy)` Jar is found on `classpath`, the same Jar will be added to `groovyClasspath`.
- If a `groovy(-indy)` Jar is found on `classpath`, and the project has at least one repository declared, a corresponding `groovy(-indy)` repository dependency will be added to `groovyClasspath`.
- Otherwise, execution of the task will fail with a message saying that `groovyClasspath` could not be inferred.

## 24.6. Convention properties

The Groovy plugin does not add any convention properties to the project.

## 24.7. Source set properties

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 Section 21.3, “Conventions”).

Table 24.4. Groovy plugin - source set properties

Property name | Type | Default value | Description
`groovy` | `SourceDirectorySet` (read-only) | Not null | The Groovy source files of this source set. Contains all `.groovy` and `.java` files found in the Groovy source directories, and excludes all other types of files.
`groovy.srcDirs` | `Set<File>`. Can set using anything described in Section 16.5, “Specifying a set of input files”. | `[`projectDir`/src/`name`/groovy]` | The source directories containing the Groovy source files of this source set. May also contain Java source files for joint compilation.
`allGroovy` | `FileTree` (read-only) | Not null | All Groovy source files of this source set. Contains only the `.groovy` files found in the Groovy source directories.

These properties are provided by a convention object of type `GroovySourceSet`.

The Groovy plugin also modifies some source set properties:

Table 24.5. Groovy plugin - source set properties

Property name | Change
`allJava` | Adds all `.java` files found in the Groovy source directories.
`allSource` | Adds all source files found in the Groovy source directories.

## 24.8. GroovyCompile

The Groovy plugin adds a `GroovyCompile` task for each source set in the project. The task type extends the `JavaCompile` task (see Section 23.11, “CompileJava”). Unless `groovyOptions.useAnt` is set to `true`, Gradle's native Groovy compiler integration is used. For most projects, this is the better choice than the Ant-based compiler. The `GroovyCompile` task supports most configuration options of the official Groovy compiler.

Table 24.6. Groovy plugin - GroovyCompile properties

Task Property | Type | Default Value
`classpath` | `FileCollection` | ``sourceSet`.compileClasspath`
`source` | `FileTree`. Can set using anything described in Section 16.5, “Specifying a set of input files”. | ``sourceSet`.groovy`
`destinationDir` | `File`. | ``sourceSet`.output.classesDir`
`groovyClasspath` | `FileCollection` | `groovy` configuration if non-empty; Groovy library found on `classpath` otherwise

[11] We are using the same conventions as introduced by Russel Winder's Gant tool (http://gant.codehaus.org).