Chapter 56. The Groovy Plugin

Table of Contents

56.1. Usage
56.2. Tasks
56.3. Project layout
56.4. Dependency management
56.5. Automatic configuration of groovyClasspath
56.6. Convention properties
56.7. Source set properties
56.8. GroovyCompile
56.9. Compiling and testing for Java 6 or Java 7

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 you 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.

56.1. Usage

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

Example 56.1. Using the Groovy plugin

build.gradle

apply plugin: 'groovy'

56.2. Tasks

The Groovy plugin adds the following tasks to the project.

Table 56.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.

compileSourceSetGroovy

compileSourceSetJava

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 56.2. Groovy plugin - additional task dependencies

Task name Depends on

classes

compileGroovy

testClasses

compileTestGroovy

sourceSetClasses

compileSourceSetGroovy

Figure 56.1. Groovy plugin - tasks

Groovy plugin - tasks

56.3. Project layout

The Groovy plugin assumes the project layout shown in Table 56.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.[28] None of these directories need to exist or have anything in them; the Groovy plugin will simply compile whatever it finds.

Table 56.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.

56.3.1. Changing the project layout

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

Example 56.2. Custom Groovy source layout

build.gradle

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

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

56.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. 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 56.3. Configuration of Groovy dependency

build.gradle

repositories {
    mavenCentral()
}

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

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

Example 56.4. Configuration of Groovy test dependency

build.gradle

dependencies {
    testCompile 'org.codehaus.groovy:groovy-all:2.4.10'
}

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 56.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 56.6. Configuration of Groovy file dependency

build.gradle

repositories {
    flatDir { dirs 'lib' }
}

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

The “module” reference may be new to you. See Chapter 25, Dependency Management for more information about this and other information about dependency management.

56.5. Automatic configuration of groovyClasspath

The GroovyCompile and Groovydoc tasks consume Groovy code 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, that 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.

Note that the “-indy” variation of each jar refers to the version with invokedynamic support.

56.6. Convention properties

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

56.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.

Table 56.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 20.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 56.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.

56.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 47.11, “CompileJava”). The GroovyCompile task supports most configuration options of the official Groovy compiler.

Table 56.6. Groovy plugin - GroovyCompile properties

Task Property Type Default Value

classpath

FileCollection

sourceSet.compileClasspath

source

FileTree. Can set using anything described in Section 20.5, “Specifying a set of input files”.

sourceSet.groovy

destinationDir

File.

sourceSet.groovy.outputDir

groovyClasspath

FileCollection

groovy configuration if non-empty; Groovy library found on classpath otherwise

56.9. Compiling and testing for Java 6 or Java 7

The Groovy compiler will always be executed with the same version of Java that was used to start Gradle. You should set sourceCompatibility and targetCompatibility to 1.6 or 1.7. If you also have Java sources, you can follow the same steps as for the Java plugin to ensure the correct Java compiler is used.

Example 56.7. Configure Java 6 build for Groovy

gradle.properties

# in $HOME/.gradle/gradle.properties
java6Home=/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

build.gradle

sourceCompatibility = 1.6
targetCompatibility = 1.6

assert hasProperty('java6Home') : "Set the property 'java6Home' in your your gradle.properties pointing to a Java 6 installation"
def javaExecutablesPath = new File(java6Home, 'bin')
def javaExecutables = [:].withDefault { execName ->
    def executable = new File(javaExecutablesPath, execName)
    assert executable.exists() : "There is no ${execName} executable in ${javaExecutablesPath}"
    executable
}
tasks.withType(AbstractCompile) {
    options.with {
        fork = true
        forkOptions.javaHome = file(java6Home)
    }
}
tasks.withType(Javadoc) {
    executable = javaExecutables.javadoc
}
tasks.withType(Test) {
    executable = javaExecutables.java
}
tasks.withType(JavaExec) {
    executable = javaExecutables.java
}



[28] We are using the same conventions as introduced by Russel Winder’s Gant tool (https://gant.github.io/).