Chapter 57. The Groovy Plugin

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

apply plugin: 'groovy'

The Groovy plugin adds the following tasks to the project.

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

Figure 57.1. Groovy plugin - tasks

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

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

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

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:

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:

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.

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:

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.

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:

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

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

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.

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

The Groovy plugin also modifies some source set properties:

The Groovy plugin adds a GroovyCompile task for each source set in the project. The task type extends the JavaCompile task (see Section 48.11, “CompileJava”). The GroovyCompile task supports most configuration options of the official Groovy compiler.

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.

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

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
}