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.
To use the Groovy plugin, include in your build script:
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 |
compile |
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 |
compileSourceSet Groovy |
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. [9] 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/
|
Java source for the given source set |
src/
|
Resources for the given source set |
src/
|
Groovy sources for the given source set. May also contain Java sources for joint compilation. |
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. [10]
If Groovy is used both 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.0.5'
}
If Groovy is only used for test code, the Groovy dependency should be added to the testCompile
(but not the compile
) configuration:
Example 24.4. Configuration of Groovy test dependency
build.gradle
dependencies {
testCompile "org.codehaus.groovy:groovy-all:2.0.5"
}
To use the same 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 explicitly choosing a Groovy version.
Example 24.5. Configuration of bundled Groovy dependency
build.gradle
dependencies { compile localGroovy() }
In earlier Gradle versions, the Groovy dependency was instead added to the groovy
configuration.
This is no longer the preferred approach, but is still supported for backwards compatibility.
Example 24.6. Configuration of Groovy configuration
build.gradle
dependencies {
groovy "org.codehaus.groovy:groovy-all:2.0.5"
}
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.7. Configuration of Groovy file dependency
build.gradle
repositories { flatDir { dirs 'lib' } } dependencies { groovy module(':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(':ant:1.7.0') { dependencies(':ant-junit:1.7.0:jar', ':ant-launcher:1.7.0') } } }
When adding custom GroovyCompile
and Groovydoc
tasks, it's important to understand
that these tasks consume Groovy in two ways: on their classpath
, and on their groovyClasspath
.
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.
Unless groovyClasspath
is explicitly configured for a task, the Groovy (base) plugin will try to infer
the Groovy library to be used from the task'sclasspath
. For example, if classpath
contains
groovy-all-2.0.5.jar
, the plugin will add the same dependency to groovyClasspath
. If the project
has at least one repository defined, an external dependency will be added (e.g. "org.codehaus.groovy:groovy-all:2.0.5"
);
otherwise, a file dependency will be added.
Note: When using the groovy
rather than the groovy-all
artifact, automatic configuration of
groovyClasspath
will only work correctly if the project declares a repository that contains the groovy
artifact along with a descriptor (pom.xml
or ivy.xml
) listing its dependencies. Otherwise, only the
artifact itself will be added to groovyClasspath
, which will likely result in a NoClassDefFoundError
during compilation.
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”.
|
[
|
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. |
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 |
|
source
|
FileTree . Can set using anything described in Section 16.5, “Specifying a set of input files”. |
|
destinationDir
|
File . |
|
groovyClasspath
|
FileCollection |
groovy configuration if non-empty; Groovy library found on classpath otherwise |
[9] We are using the same conventions as introduced by Russel Winder's Gant tool (http://gant.codehaus.org).
[10] GroovyCompile
Groovydoc
groovyClasspath
classpath
groovy-all(-indy)
groovy(-indy)
groovyClasspath
groovyClasspath