This user guide, like Gradle itself, is under very active development. Some parts of Gradle aren't documented as completely as they need to be. Some of the content presented won't be entirely clear or will assume that you know more about Gradle than you do. We need your help to improve this user guide. You can find out more about contributing to the documentation at the Gradle web site.

You can find more examples, and some additions to this user guide, on the wiki. You can also contribute your own examples and extra content there.

Here is a list of some of Gradle's features.

Gradle scales very well. It significantly increases your productivity, from rather simple single project builds up to huge enterprise multi-project builds.

Gradle is build by Gradle. From a build perspective Gradle is a simple project. But achieving the high degree of automation we have, would have been very hard (and expensive) to achieve with Ant or Maven.

We think the advantages of an internal DSL (based on a dynamic language) over XML are tremendous in case of build scripts. There are a couple of dynamic languages out there. Why Groovy? The answer lies in the context Gradle is operating in. Although Gradle is a general purpose build tool at its core, its main focus are Java projects. ^[2] In such projects obviously the team members know Java. One problem we see with Ant ^[3] and Maven is, that it involves a lot of knowledge only available to the build master. Such builds are very hard to comprehend, let alone to modify by a person not deeply involved with those tools. We think a build should be as transparent as possible to all team members.

You might argue why not using Java then as the language for build scripts. We think this is a valid question. It would have the highest transparency for your team and the lowest learning curve. But due to limitations of Java such a build language would not be as nice, expressive and powerful as it could be. ^[4] Languages like Python, Groovy or Ruby do a much better job here. We have chosen Groovy as it offers by far the highest transparency for Java people. Its base syntax is the same as Java's as well as its type system, its package structure other things. Groovy builds a lot on top of that. But on a common ground with Java.

For Java teams which share also Python or Ruby knowledge or are happy to learn it the above arguments don't apply. In the near future Gradle wants to give you a choice between different languages for your build scripts. For Jython or JRuby this should be easy to implement. If members of those communities are interested in joining this effort, this is very much appreciated.

Here a list of features you might expect but are not available yet:

Gradle requires a Java JDK to be installed. Gradle ships with its own Groovy library, therefore no Groovy needs to be installed. Any existing Groovy installation is ignored by Gradle. The standard Gradle distribution requires a JDK 1.5 or higher. We also provide a distinct JDK 1.4 compatible distribution.

Gradle uses whichever JDK it finds in your path (to check, use java -version). Alternatively, you can set the JAVA_HOME environment variable to point to the install directory of the desired JDK.

You can download one of the Gradle distributions from the Gradle web site.

The Gradle distribution comes packaged as a ZIP. The full distribution contains:

For running Gradle, add GRADLE_HOME/bin to your PATH environment variable. Usually, this is sufficient to run Gradle. Optionally, you may also want to set the GRADLE_HOME environment variable to point to the root directory of your Gradle installation.

You run Gradle via the gradle command. To check if Gradle is properly installed just type gradle -v and you should get an output like:

------------------------------------------------------------
Gradle 0.8
------------------------------------------------------------

Gradle buildtime: Monday, September 28, 2009 1:53:43 PM CEST
Groovy: 1.6.4
Ant: Apache Ant version 1.7.0 compiled on December 13 2006
Ivy: 2.1.0-rc2
Java: 1.6.0_15
JVM: 14.1-b02-90
JVM Vendor: Apple Inc.
OS Name: Mac OS X

JVM options for running Gradle can be set via environment variables. You can use GRADLE_OPTS or JAVA_OPTS. Those variables can be used together. JAVA_OPTS is by convention an environment variable shared by many Java applications. A typical use case would be to set the HTTP proxy in JAVA_OPTS and the memory options in GRADLE_OPTS. Those variables can also be set at the beginning of the gradle or gradlew script.

In Gradle the most basic building block is the task. The tasks for your build are defined in the build script. To try this out, create the following build script named build.gradle.

task hello << {
    println 'Hello world!'
}

In a command-line shell, enter into the containing directory and execute the build script by running gradle -q hello:

> gradle -q hello
Hello world!

What's going on here? This build file defines a single task, called hello, and adds an action to it. When you run gradle hello, Gradle executes the hello task, which in turn executes the action you've provided. The action is simply a closure containing some Groovy code to execute.

If you think this looks similar to Ant's targets, well, you are right. Gradle tasks are the equivalent to Ant targets. But as you will see, they are much more powerful. We have used a different terminology than Ant as we think the word task is more expressive than the word target. Unfortunately this introduces a terminology clash with Ant, as Ant calls its commands, such as javac or copy, tasks. So when we talk about tasks, we always mean Gradle tasks, which are the equivalent to Ant's targets. If we talk about Ant tasks (Ant commands), we explicitly say ant task.

Gradle's build scripts expose to you the full power of Groovy. As an appetizer, have a look at this:

task upper << {
    String someString = 'mY_nAmE'
    println "Original: " + someString 
    println "Upper case: " + someString.toUpperCase()
}

> gradle -q upper
Original: mY_nAmE
Upper case: MY_NAME

or

task count << {
    4.times { print "$it " }
}

> gradle -q count
0 1 2 3

As you probably have guessed, you can declare dependencies between your tasks.

task hello << {
    println 'Hello world!'
}
task intro(dependsOn: hello) << {
    println "I'm Gradle"
}

> gradle -q intro
Hello world!
I'm Gradle

To add a dependency, the corresponding task does not need to exist.

task taskX(dependsOn: 'taskY') << {
    println 'taskX'
}
task taskY << {
    println 'taskY'
}

> gradle -q taskX
taskY
taskX

The dependency of taskX to taskY is declared before taskY is defined. This is very important for multi-project builds. Task dependencies are discussed in more detail in Section 13.4, “Adding dependencies to a task”.

Please notice, that you can't use a shortcut notation (see Section 4.6, “Shortcut notations”) when referring to task, which is not defined yet.

The power of Groovy can be used for more than defining what a task does. For example, you can also use it to dynamically create tasks.

4.times { counter ->
    task "task$counter" << {
        println "I'm task number $counter"
    }
}

> gradle -q task1
I'm task number 1

Once tasks are created they can be accessed via an API. This is different to Ant. For example you can create additional dependencies.

4.times { counter ->
    task "task$counter" << {
        println "I'm task number $counter"
    }
}
task0.dependsOn task2, task3

> gradle -q task0
I'm task number 2
I'm task number 3
I'm task number 0

Or you can add behavior to an existing task.

task hello << {
    println 'Hello Earth'
}
hello.doFirst {
    println 'Hello Venus'
}
hello.doLast {
    println 'Hello Mars'
}
hello << {
    println 'Hello Jupiter'
}

> gradle -q hello
Hello Venus
Hello Earth
Hello Mars
Hello Jupiter

The calls doFirst and doLast can be executed multiple times. They add an action to the beginning or the end of the task's actions list. When the task executes, the actions in the action list are executed in order. The << operator is simply an alias for doLast.

As you might have noticed in the previous examples, there is a convenient notation for accessing an existing task. Each task is available as a property of the build script:

task hello << {
    println 'Hello world!'
}
hello.doLast {
    println "Greetings from the $hello.name task."
}

> gradle -q hello
Hello world!
Greetings from the hello task.

This enables very readable code, especially when using the out of the box tasks provided by the plugins (e.g. compile).

You can assign arbitrary new properties to any task.

task myTask
myTask.myProperty = 'myCustomPropValue'

task showProps << {
    println myTask.myProperty
}

> gradle -q showProps
myCustomPropValue

Ant tasks are first-class citizens in Gradle. Gradle provides excellent integration for Ant tasks simply by relying on Groovy. Groovy is shipped with the fantastic AntBuilder. Using Ant tasks from Gradle is as convenient and more powerful than using Ant tasks from a build.xml file. Let's look at an example:

task checksum << {
    def files = file('../antChecksumFiles').listFiles().sort()
    files.each { File file ->
        if (file.isFile()) {
            ant.checksum(file: file, property: file.name)
            println "$file.name Checksum: ${ant.properties[file.name]}"
        }
    }
}

> gradle -q checksum
agile_manifesto.html Checksum: 2dd24e01676046d8dedc2009a1a8f563
agile_principles.html Checksum: 659d204c8c7ccb5d633de0b0d26cd104
dylan_thomas.txt Checksum: 91040ca1cefcbfdc8016b1b3e51f23d3

There is lots more you can do with Ant in your build scripts. You can find out more in Chapter 16, Using Ant from Gradle.

Gradle scales in how you can organize your build logic. The first level of organizing your build logic for the example above, is extracting a method.

task checksum << {
    fileList('../antChecksumFiles').each {File file ->
        ant.checksum(file: file, property: "cs_$file.name")
        println "$file.name Checksum: ${ant.properties["cs_$file.name"]}"
    }
}

task length << {
    fileList('../antChecksumFiles').each {File file ->
        ant.length(file: file, property: "lt_$file.name")
        println "$file.name Length: ${ant.properties["lt_$file.name"]}"
    }
}

File[] fileList(String dir) {
    file(dir).listFiles({file -> file.isFile() } as FileFilter).sort()
}

> gradle -q checksum
agile_manifesto.html Checksum: 2dd24e01676046d8dedc2009a1a8f563
agile_principles.html Checksum: 659d204c8c7ccb5d633de0b0d26cd104
dylan_thomas.txt Checksum: 91040ca1cefcbfdc8016b1b3e51f23d3

Later you will see that such methods can be shared among subprojects in multi-project builds. If your build logic becomes more complex, Gradle offers you other very convenient ways to organize it. We have devoted a whole chapter to this. See Chapter 34, Organizing Build Logic.

Gradle allows you to define one or more default tasks for your build.

defaultTasks 'clean', 'run'

task clean << {
    println 'Default Cleaning!'
}

task run << {
    println 'Default Running!'
}

task other << {
    println "I'm not a default task!"
}

> gradle -q
Default Cleaning!
Default Running!

This is equivalent to running gradle clean run. In a multi-project build every subproject can have its own specific default tasks. If a subproject does not specify default tasks, the default tasks of the parent project are used (if defined).

As we describe in full detail later (See Chapter 30, The Build Lifecycle) Gradle has a configuration phase and an execution phase. After the configuration phase Gradle knows all tasks that should be executed. Gradle offers you a hook to make use of this information. A use-case for this would be to check if the release task is part of the tasks to be executed. Depending on this you can assign different values to some variables.

In the following example, execution of distribution and release tasks results in different value of version variable.

gradle.taskGraph.whenReady {taskGraph ->
    if (taskGraph.hasTask(':release')) {
        version = '1.0'
    } else {
        version = '1.0-SNAPSHOT'
    }
}

task distribution << {
    println "We build the zip with version=$version"
}
task release(dependsOn: 'distribution') << {
    println 'We release now'
}

> gradle -q distribution
We build the zip with version=1.0-SNAPSHOT

> gradle -q release
We build the zip with version=1.0
We release now

The important thing is, that the fact that the release task has been chosen, has an effect before the release task gets executed. Nor has the release task to be the primary task (i.e. the task passed to the gradle command).

This is not the end of the story for tasks. So far we have worked with simple tasks. Tasks will be revisited in Chapter 13, More about Tasks and when we look at the Java Plugin in Chapter 18, The Java Plugin.

Let's look at a simple example. To use the Java plugin, add the following to your build file:

usePlugin 'java'

This is all you need to define a Java project. This will apply the Java plugin to your project, which adds a number of tasks to your project.

Gradle expects to find your production source code under src/main/java and your test source code under src/test/java. In addition, any files under src/main/resources will be included in the JAR file as resources, and any files under src/test/resources will be included in the classpath used to run the tests. All output files are created under the build directory, with the JAR file ending up in the build/libs directory.

> gradle build
:compileJava
:processResources
:classes
:jar
:assemble
:compileTestJava
:processTestResources
:testClasses
:test
:check
:build

BUILD SUCCESSFUL

Total time: 1 secs

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

sourceCompatibility = 1.5
version = '1.0'
manifest.mainAttributes(
    'Implementation-Title': 'Gradle Quickstart',
    'Implementation-Version': version
)

test {
    options.systemProperties['property'] = 'value'
}

uploadArchives {
    repositories {
       flatDir(dirs: file('repos'))
    }
}

usePlugin 'eclipse'

usePlugin 'java'

usePlugin 'eclipse'

sourceCompatibility = 1.5
version = '1.0'
manifest.mainAttributes(
    'Implementation-Title': 'Gradle Quickstart',
    'Implementation-Version': version
)

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

test {
    options.systemProperties['property'] = 'value'
}

uploadArchives {
    repositories {
       flatDir(dirs: file('repos'))
    }
}

Now let's look at a typical multi-project build. Below is the layout for the project:

multiproject/
  api/
  services/
    webservice/
  shared/

Here we have three projects. Project api produces a JAR file which is shipped to the client to provide them a Java client for your XML webservice. Project webservice is a webapp which returns XML. Project shared contains code used both by api and webservice.

include "shared", "api", "services:webservice"

subprojects {
    usePlugin 'java'
    usePlugin 'eclipse'

    repositories {
       mavenCentral()
    }

    dependencies {
        testCompile 'junit:junit:4.7'
    }

    group = 'org.gradle'
    version = '1.0'
    manifest.mainAttributes(provider: 'gradle')
}

dependsOnChildren()

dependencies {
    compile project(':shared')
}

task dist(type: Zip) {
    dependsOn spiJar
    from configurations.runtime
    from spiJar.archivePath
    fileSet dir: 'src/dist'
}

In this chapter, you have seen how to do some of the things you commonly need to build a Java based project. This chapter is not exhaustive, and there are many other things you can do with Java projects in Gradle. These are dealt with in later chapters. Also, a lot of the behaviour you have seen in this chapter is configurable. For example, you can change where Gradle looks Java source files, or add extra tasks, or you can change what any task actually does. Again, you will see how this works in later chapters.

You can find out more about the Java plugin in Chapter 18, The Java Plugin, and you can find more sample Java projects in the samples/java directory in the Gradle distribution.

Let's look at an example. To use the Groovy plugin, add the following to your build file:

usePlugin 'groovy'

This will also apply the Java plugin to the project, if it has not already been applied. The Groovy plugin extends the compile task to look for source files in directory src/main/groovy, and the compileTest task to look for test source files in directorysrc/test/groovy. The compile tasks use joint compilation for these directories, which means they can contain a mixture of java and groovy source files.

To use the groovy compilation tasks, you must also declare the Groovy version to use and where to find the Groovy libraries. You do this by adding a dependency to the groovy configuration. The compile configuration inherits this dependency, so the groovy libraries will be included in classpath when compiling Groovy and Java source. For our sample, we will use Groovy 1.6.0 from the public Maven repository:

repositories {
    mavenCentral()
}

dependencies {
    groovy group: 'org.codehaus.groovy', name: 'groovy', version: '1.6.0'
}

Here is our complete build file:

usePlugin 'groovy'

repositories {
    mavenCentral()
}

dependencies {
    groovy group: 'org.codehaus.groovy', name: 'groovy', version: '1.6.0'
    testCompile group: 'junit', name: 'junit', version: '4.7'
}

Running gradle build will compile, test and JAR your project.

This chapter describes a very simple Groovy project. Usually, a real project will require more than this. Because a Groovy project is a Java project, whatever you can do with a Java project, you can also do with a Groovy project.

You can find out more about the Groovy plugin in Chapter 19, The Groovy Plugin, and you can find more sample Groovy projects in the samples/groovy directory in the Gradle distribution.

To build a WAR file, you apply the War plugin to your project:

usePlugin 'war'

This also applies the Java plugin to your project. Running gradle build will compile, test and WAR your project. Gradle will look for the source files to include in the WAR file in src/main/webapp. Your compiled classes, and their runtime dependencies are also included in the WAR file.

To run your web application, you apply the Jetty plugin to your project:

usePlugin 'jetty'

This also applies the War plugin to your project. Running gradle jettyRun will run your web application in an embedded Jetty web container. Running gradle jettyRunWar will build and test the WAR file, and then run it in an embedded web container.

TODO: which url, configure port, uses source files in place and can edit your files and reload.

You can find out more about the War plugin in Chapter 21, The War Plugin and the Jetty plugin in Chapter 22, The Jetty Plugin. You can find more sample Java projects in the samples/webApplication directory in the Gradle distribution.

Artifacts are grouped into configurations. A configuration is simply a set of files with a name. You can use them to declare the external dependencies your project has, or to declare the artifacts which your project publishes.

To define a configuration:

configurations {
    compile
}

To access a configuration:

println configurations.compile.name
println configurations['compile'].name

To configure a configuration:

configurations {
    compile {
        description = 'compile classpath'
        transitive = true
    }
    runtime {
        extendsFrom compile
    }
}
configurations.compile {
    description = 'compile classpath'
}

Artifacts are stored in repositories.

To use maven central repository:

repositories {
    mavenCentral()
}

To use a local directory:

repositories {
    flatDir name: 'localRepository', dirs: 'lib'
}

You can also use any Ivy resolver. You can have multiple repositories.

To access a repository:

println repositories.localRepository.name
    println repositories['localRepository'].name

To configure a repository:

repositories {
    localRepository {
        addArtifactPattern(file('lib').absolutePath + '/[name]/[revision]/[name]-[revision].[ext]')
    }
}
repositories.localRepository {
    addArtifactPattern(file('lib').absolutePath + '/[name]/[revision]/[name]-[revision].[ext]')
}

To define an external dependency, you add a dependency to a configuration:

configurations {
    compile
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
}

group and version are optional

TBD - configuring an external dependency

To use the external dependencies of a configuration:

task listJars << {
    configurations.compile.each { File file -> println file.name }
}

> gradle -q listJars
commons-collections-3.2.jar

TBD

Configurations are contained in a ConfigurationContainer . Each configuration implements the Configuration .

You can execute multiple tasks in a single build by listing each of the tasks on the command-line. For example, the command gradle compile test will execute the compile and test tasks. Gradle will execute the tasks in the order that they are listed on the command-line, and will also execute the dependencies for each task. Each task is executed once only, regardless of why it is included in the build: whether it was specified on the command-line, or it a dependency of another task, or both. Let's look at an example.

Below four tasks are defined. Both dist and test depend on the compile task. Running gradle dist test for this build script results in the compile task being executed only once.

Figure 9.1. Task dependencies

task compile << {
    println 'compiling source'
}

task compileTest(dependsOn: compile) << {
    println 'compiling unit tests'
}

task test(dependsOn: [compile, compileTest]) << {
    println 'running unit tests'
}

task dist(dependsOn: [compile, test]) << {
    println 'building the distribution'
}

> gradle dist test
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

Because each task is executed once only, executing gradle test test is exactly the same as executing gradle test.

You can exclude a task from being executed using the -x command-line option and providing the name of the task to exclude. Let's try this with the sample build file above.

> gradle dist -x test
:compile
compiling source
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

You can see from the output of this example, that the test task is not executed, even though it is a dependency of the dist task. You will also notice that the test task's dependencies, such as compileTest are not executed either. Those dependencies of test that are required by another task, such as compile, are still executed.

When you specify tasks on the command-line, you don't have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, in the sample build above, you can execute task dist by running gradle d:

> gradle d
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

You can also abbreviate each word in a camel case task name. For example, you can execute task compileTest by running gradle compTest or even gradle cT

> gradle cT
:compile
compiling source
:compileTest
compiling unit tests

BUILD SUCCESSFUL

Total time: 1 secs

You can also use these abbreviations with the -x command-line option.

When you run the gradle command, it looks for a build file in the current directory. You can use the -b option to select another build file. For example:

task hello << {
    println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
}

> gradle -q -b subdir/myproject.gradle hello
using build file 'myproject.gradle' in 'subdir'.

Alternatively, you can use the -p option to specify the project directory to use:

> gradle -q -p subdir hello
using build file 'build.gradle' in 'subdir'.

Gradle provides several command-line options which show particular details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems.

Running gradle --tasks gives you a list of the tasks which make up the build, broken down by project. This report shows the default tasks, if any, of each project, and the description and dependencies of each task. Below is an example of this report:

> gradle -q --tasks
------------------------------------------------------------
Root Project
------------------------------------------------------------
Default Tasks: dists

:clean - Deletes the build directory (build)
:dists 
   -> :api:libs, :webapp:libs

------------------------------------------------------------
Project :api
------------------------------------------------------------
:api:libs 
rule - build<ConfigurationName>: builds the artifacts of the given configuration

------------------------------------------------------------
Project :webapp
------------------------------------------------------------
:webapp:libs 
rule - build<ConfigurationName>: builds the artifacts of the given configuration

Running gradle --dependencies gives you a list of the dependencies of the build, broken down by project. This report shows the configurations of each project. For each configuration, the direct and transitive dependencies of that configuration are shown. Below is an example of this report:

> gradle -q --dependencies
------------------------------------------------------------
Root Project
------------------------------------------------------------
No configurations

------------------------------------------------------------
Project :api
------------------------------------------------------------
compile
|-----junit:junit:4.7:default

------------------------------------------------------------
Project :webapp
------------------------------------------------------------
compile
|-----commons-io:commons-io:1.2:default

Running gradle --properties gives you a list of the properties of each project in the build.

You can also use the project report plugin to add a number of reporting tasks to your project.

Sometimes you are interested in which tasks are executed in which order for a given set of tasks specified on the command line, but you don't want the tasks to be executed. You can use the -m option for this. For example gradle -m clean compile shows you all tasks to be executed as part of the clean and compile tasks. This is complementary to the -t, which shows you all available tasks for execution.

In this chapter, you have seen some of the things you can do with Gradle from the command-line. You can find out more about the gradle command in Appendix B, Gradle Command Line.

The Task Tree shows a hierarchical display of all projects and their tasks. Double clicking a task executes it.

There is also a filter so that uncommon tasks can be hidden. You can toggle the filter via the Filter button. Editing the filter allows you to configure which tasks and projects are shown. Hidden tasks show up in red. Note: newly created tasks will show up by default (versus being hidden by default).

The Task Tree context menu provides the following options:

The Favorites tab is place to store commonly-executed commands. These can be complex commands (anything that's legal to gradle) and you can provide them with a display name. This is useful for creating, say, a custom build command that explicitly skips tests, documentation, and samples that you could call "fast build".

You can reorder favorites to your liking and even export them to disk so they can imported by others. If you edit them, you are given options to "Always Show Live Output." This only applies if you have 'Only Show Output When Errors Occur'. This override always forces the output to be shown.

The Command Line tab is place to execute a single gradle command directly. Just enter whatever you would normally enter after 'gradle' on the command line. This also provides a place to try out commands before adding them to favorites.

The Setup tab allows configuration of some general settings.

Figure 10.2. GUI Setup

There is a common situation, that multiple tasks depend on the existence of a directory. Of course you can deal with this by adding a mkdir to the beginning of those tasks. But this is kind of bloated. There is a better solution (works only if the tasks that need the directory have a dependsOn relationship):

classesDir = new File('build/classes')
task resources << {
    classesDir.mkdirs()
    // do something
}
task compile(dependsOn: 'resources') << {
    if (classesDir.isDirectory()) {
        println 'The class directory exists. I can operate'
    }
    // do something
}

> gradle -q compile
The class directory exists. I can operate

But Gradle offers you also Directory Tasks to deal with this.

classes = dir('build/classes')
task resources(dependsOn: classes) << {
    // do something
}
task otherResources(dependsOn: classes) << {
    if (classes.dir.isDirectory()) {
        println 'The class directory exists. I can operate'
    }
    // do something
}

> gradle -q otherResources
The class directory exists. I can operate

A Directory Task is a simple task whose name is a relative path to the project dir ^[6] . During the execution phase the directory corresponding to this path gets created if it does not exist yet. Another interesting thing to note in this example, is that you can also pass tasks objects to the dependsOn declaration of a task.

Gradle offers a variety of ways to add properties to your build. With the -D command line option you can pass a system property to the JVM which runs Gradle. The -D option of the gradle command has the same effect as the -D option of the java command.

You can also directly add properties to your project objects using properties files. You can place a gradle.properties file in the Gradle user home directory (defaults to USER_HOME/.gradle) or in your project directory. For multi-project builds you can place gradle.properties files in any subproject directory. The properties of the gradle.properties can be accessed via the project object. The properties file in the user's home directory has precedence over property files in the project directories.

You can also add properties directly to your project object via the -P command line option. For more exotic use cases you can even pass properties directly to the project object via system and environment properties. For example if you run a build on a continuous integration server where you have no admin rights for the machine. Your build script needs properties which values should not be seen by others. Therefore you can't use the -P option. In this case you can add an environment property in the project administration section (invisible to normal users). ^[7] If the environment property follows the pattern ORG_GRADLE_PROJECT_propertyName=somevalue, propertyName is added to your project object. If in the future CI servers support Gradle directly, they might start Gradle via its main method. Therefore we already support the same mechanism for system properties. The only difference is the pattern, which is org.gradle.project.propertyName .

With the gradle.properties files you can also set system properties. If a property in such a file has the prefix systemProp. the property and its value are added to the system properties, without the prefix.

gradlePropertiesProp=gradlePropertiesValue
systemPropertiesProp=shouldBeOverWrittenBySystemProp
envPropertiesProp=shouldBeOverWrittenByEnvProp
systemProp.system=systemValue

task printProps << {
    println commandLineProjectProp
    println gradlePropertiesProp
    println systemProjectProp
    println envProjectProp
    println System.properties['system']
}

> gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps
commandLineProjectPropValue
gradlePropertiesValue
systemPropertyValue
envPropertyValue
systemValue

Setting a proxy for web access (for example for downloading dependencies) is easy. Gradle does not need to provide special functionality for this. The JVM can be instructed to go via proxy by setting certain system properties. You could set these system properties directly in your build script with System.properties['proxy.proxyUser'] = 'userid'. An arguably nicer way is shown in Section 11.2, “Gradle properties and system properties”. Your gradle.properties file could look like this:

systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost

We could not find a good overview for all possible proxy settings. One place to look are the constants in a file from the ant project. Here a link to the svn view. The other is a Networking Properties page from the JDK docs. If anyone knows a better overview please let us know via the mailing list.

To improve the responsiveness Gradle caches the compiled build script by default. The first time you run a build for a project, Gradle creates a .gradle directory in which it puts the compiled build script. The next time you run this build, Gradle uses the compiled build script, if the timestamp of the compiled script is newer than the timestamp of the actual build script. Otherwise the build script gets compiled and the new version is stored in the cache. If you run Gradle with the -x option, any existing cache is ignored and the build script is compiled and executed on the fly. If you run Gradle with the -r option, the build script is always compiled and stored in the cache. That way you can always rebuild the cache if for example the timestamps for some reasons don't reflect that the build script needs to be recompiled.

You can configure arbitrary objects in the following very readable way.

task configure << {
    pos = configure(new java.text.FieldPosition(10)) {
        beginIndex = 1
        endIndex = 5
    }
    println pos.beginIndex
    println pos.endIndex
}

> gradle -q configure
1
5

In the tutorial in Chapter 4, Build Script Basics we used, for example, the task() method. Where does this method come from? We said earlier that the build script defines a project in Gradle. For Gradle, this means that it creates an instance of Project and associates this Project object with the build script. As the build script executes, it configures this Project object.

Let's try this out and try to access the name property of the Project object.

task check << {
    println name
    println project.name
}

> gradle -q check
projectApi
projectApi

Both println statements print out the same property. The first uses auto-delegation to the Project object, for properties not defined in the build script. The other statement uses the project property available to any build script, which returns the associated Project object. Only if you define a property or a method which has the same name as a member of the Project object, you need to use the project property.

Have a look at the Project API to find out more about project properties and methods.

projectCoreProperties/
  build.gradle
  subProject/
    build.gradle

task check << {
    allprojects {
        println "project path $path"
        println "  project name = $name"
        println "  project dir = '${rootProject.relativePath(projectDir)}'"
        println "  build file = '${rootProject.relativePath(buildFile)}'"
        println "  build dir = '${rootProject.relativePath(buildDir)}'"
    }
}

> gradle -q check
project path :
  project name = projectCoreProperties
  project dir = ''
  build file = 'build.gradle'
  build dir = 'build'
project path :subProject
  project name = subProject
  project dir = 'subProject'
  build file = 'subProject/build.gradle'
  build dir = 'subProject/build'

Many of the methods of the Project instance return task objects. We have already seen some ways that you can use task objects in Chapter 4, Build Script Basics. Look here to learn more about Task .

The project and the task API constitute the core layer of Gradle and provide all the possible interaction options with this layer. ^[8] This core-layer constitutes a language for dependency based programming. ^[9] There are many other projects providing such a language. There is Ant for Java, Rake and Rant for Ruby, SCons for Python, the good old Make and many more. ^[10] We think that one thing that makes Gradle special compared to the other tools, is its strong support for applying dependency based programming on multi-project builds. We also think that just Gradle's core layer (together with its integration of the Ant tasks), provides a more convenient build system than Ant's core layer.

We have already seen how to define tasks using a keyword style in Chapter 4, Build Script Basics. There are a few variations on this style, which you may need to use in certain situations. For example, the keyword style does not work in expressions.

task(hello) << {
    println "hello"
}

task(copy, type: Copy) {
    from(file('srcDir'))
    into(buildDir)
}

You can also use strings for the task names:

task('hello') <<
{
    println "hello"
}

task('copy', type: Copy) {
    from(file('srcDir'))
    into(buildDir)
}

There is an alternative syntax for defining tasks, which you may prefer to use:

tasks.add(name: 'hello') << {
    println "hello"
}

tasks.add(name: 'copy', type: Copy) {
    from(file('srcDir'))
    into(buildDir)
}

Here we add tasks to the tasks collection. Have a look at TaskContainer for more variations of the add() method.

You often need to locate the tasks that you have defined in the build file, for example, to configure them or use them for dependencies. There are a number of ways you can do this. Firstly, each task is available as a property of the project, using the task name as the property name:

task hello

println hello.name
println project.hello.name

Tasks are also available through the tasks collection.

task hello

println tasks.hello.name
println tasks['hello'].name

You can access tasks from any project using the task's path using the tasks.getByPath() method. You can call the getByPath() method with a task name, or a relative path, or an absolute path.

project(':projectA') {
    task hello
}

task hello

println tasks.getByPath('hello').path
println tasks.getByPath(':hello').path
println tasks.getByPath('projectA:hello').path
println tasks.getByPath(':projectA:hello').path

> gradle -q hello
:hello
:hello
:projectA:hello
:projectA:hello

Have a look at TaskContainer for more options for locating tasks.

As an example, let's look at the Copy task provided by Gradle. To create a Copy task for your build, you can declare in your build script: ^[11]

task myCopy(type: Copy)

This creates a copy task with no default behavior. The task can be configured using its API (see Copy ). The following examples show several different ways to achieve the same configuration.

Copy myCopy = task(myCopy, type: Copy)
myCopy.from 'resources'
myCopy.into 'target'
myCopy.include('**/*.txt', '**/*.xml', '**/*.properties')

This is similar to the way we would normally configure objects in Java. You have to repeat the context (myCopy) in the configuration statement every time. This is a redundancy and not very nice to read.

There is a more convenient way of doing this.

task(myCopy, type: Copy)
    .from('resources')
    .into('target')
    .include('**/*.txt', '**/*.xml', '**/*.properties')

You might know this approach from the Hibernates Criteria Query API or JMock. Of course the API of a task has to support this. The from, to and include methods all return an object that may be used to chain to additional configuration methods. Gradle's build-in tasks usually support this configuration style.

But there is yet another way of configuring a task. It also preserves the context and it is arguably the most readable. It is usually our favorite.

task myCopy(type: Copy)

myCopy {
   from 'resources'
   into 'target'
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

This works for any task. Line 3 of the example is just a shortcut for the tasks.getByName() method. It is important to note that if you pass a closure to the getByName() method, this closure is applied to configure the task.

There is a slightly different ways of doing this.

task myCopy(type: Copy)

myCopy.configure {
   from('source')
   into('target')
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

Every task has a configure() method, which you can pass a closure for configuring the task. Gradle uses this style for configuring objects in many places, not just for tasks.

You can also use a configuration closure when you define a task.

task copy(type: Copy) {
   from 'resources'
   into 'target'
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

There are several ways you can define the dependencies of a task. In Section 4.3, “Task dependencies” you were introduced to defining dependencies using task names. Task names can refer to tasks in the same project as the task, or to tasks in other projects. To refer to a task in another project, you prefix the name of the task with the path of the project it belongs to. Below is an example which adds a dependency from projectA:taskX to projectB:taskY:

project('projectA') {
    task taskX(dependsOn: ':projectB:taskY') << {
        println 'taskX'
    }
}

project('projectB') {
    task taskY << {
        println 'taskY'
    }
}

> gradle -q taskX
taskY
taskX

Instead of using a task name, you can define a dependency using a Task object, as shown in this example:

task taskX << {
    println 'taskX'
}

task taskY << {
    println 'taskY'
}

taskX.dependsOn taskY

> gradle -q taskX
taskY
taskX

For more advanced uses, you can define a task dependency using a closure. When evaluated, the closure is passed the task whose dependencies are being calculated. The closure should return a single Task or collection of Task objects, which are then treated as dependencies of the task. The following example adds a dependency from taskX to all the tasks in the project whose name starts with lib:

task taskX << {
    println 'taskX'
}

taskX.dependsOn {
    tasks.findAll { task -> task.name.startsWith('lib') }
}

task lib1 << {
    println 'lib1'
}

task lib2 << {
    println 'lib2'
}

task notALib << {
    println 'notALib'
}

> gradle -q taskX
lib1
lib2
taskX

For more information about task dependencies, see the Task API.

You can add a description to your task. This description is for example displayed when executing gradle -t.

task copy(type: Copy) {
   description = 'Copies the resource directory to the target directory.'
   from 'resources'
   into 'target'
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

Sometimes you want to replace a task. For example if you want to exchange a task added by the Java Plugin with a custom task of a different type. You can achieve this with:

task copy(type: Copy)

task copy(overwrite: true) << {
    println('I am the new one.')
}

> gradle -q copy
I am the new one.

Here we replace a task of type Copy with a simple task. When creating the simple task, you have to set the overwrite property to true. Otherwise Gradle throws an exception, saying that a task with such a name already exists.

Gradle offers multiple ways to skip the execution of a task.

task hello << {
    println 'hello world'
}

hello.onlyIf { !project.hasProperty('skipHello') }

> gradle hello -PskipHello
:hello SKIPPED as onlyIf is false

BUILD SUCCESSFUL

Total time: 1 secs

task compile << {
    println 'We are doing the compile.'
}

compile.doFirst {
    // Here you would put arbitrary conditions in real life. But we use this as an integration test, so we want defined behavior.
    if (true) { throw new StopExecutionException() }
}
task myTask(dependsOn: 'compile') << {
   println 'I am not affected'
}

> gradle -q myTask
I am not affected

task disableMe << {
    println 'This should not be printed if the task is disabled.'
}
disableMe.enabled = false

> gradle disableMe
:disableMe SKIPPED

BUILD SUCCESSFUL

Total time: 1 secs

Sometimes you want to have a task which behavior depends on a large or infinite number value range of parameters. A very nice and expressive way to provide such tasks are task rules:

tasks.addRule("Pattern: ping<ID>") { String taskName ->
    if (taskName.startsWith("ping")) {
        task(taskName) << {
            println "Pinging: " + (taskName - 'ping')
        }
    }
}

> gradle -q pingServer1
Pinging: Server1

The String parameter is used as a description for the rule. This description is shown when doing for example gradle -t.

Rules not just work for calling tasks from the command line. You can also create dependsOn relations on rule based tasks:

tasks.addRule("Pattern: ping<ID>") { String taskName ->
    if (taskName.startsWith("ping")) {
        task(taskName) << {
            println "Pinging: " + (taskName - 'ping')
        }
    }
}

task groupPing {
    dependsOn pingServer1, pingServer2
}

> gradle -q groupPing
Pinging: Server1
Pinging: Server2

If you are coming from Ant, such an enhanced Gradle task as Copy looks like a mixture between an Ant target and an Ant task. And this is actually the case. The separation that Ant does between tasks and targets is not done by Gradle. The simple Gradle tasks are like Ant's targets and the enhanced Gradle tasks also include the Ant task aspects. All of Gradle's tasks share a common API and you can create dependencies between them. Such a task might be nicer to configure than an Ant task. It makes full use of the type system, is more expressive and easier to maintain.

You can locate a file relative to the project directory using the Project.file() method.

// Using a relative path
File configFile = file('src/config.xml')

// Using an absolute path
configFile = file(configFile.absolutePath)

// Using a File object with a relative path
configFile = file(new File('src/config.xml'))

You can pass any object to the file() method, though usually you would pass it a String or File. The supplied object's toString() value is treated as a file path. If this path is an absolute path, it is used to construct a File instance. Otherwise, a File instance is constructed by prepending the project directory path to the supplied path.

Using this method is a useful way to convert some user provided value into an absolute File. It is preferable to using new File(somePath), as file() always evaluates the supplied path relative to the project directory, which is fixed, rather than the current working directory, which may not always be the same.

A file collection is simply a set of files. It is represented by the FileCollection interface. Many objects in Gradle implement this interface. For example, dependency configurations implement FileCollection.

One way to obtain a FileCollection instance is to use the Project.files() method. You can pass this method any number of objects, which are then converted into a set of File objects. The files() method accepts File and String arguments. These are evaluated relative to the project directory, as described in Section 14.1, “Locating files”. You can also pass collections, maps and arrays to the files() method. These are flattened and the contents converted to File instances.

FileCollection collection = files('src/file1.txt', file('src/file2.txt'), ['src/file3.txt', 'src/file4.txt'])

A file collection is iterable, and can be converted to a number of other types using the as operator. You can also add 2 file collections together using the + operator. Here are some examples.

// Iterate over the files in the collection
collection.each {File file ->
    file.name
}

// Convert the collection to various types
Set set = collection.files
Set set2 = collection as Set
List list = collection as List
String path = collection.asPath
File file = collection.singleFile
File file2 = collection as File

// Add collections together
def collection2 = collection + files('src/file3.txt')

You can also pass the files() method a closure or a Callable instance. This is called when the contents of the collection are queried, and its return value is converted to a set of File instances. The return value can be an object of any of the types supported by the files() method. This is a simple way to 'implement' the FileCollection interface.

task list << {
    File srcDir

    // Create a file collection using a closure
    collection = files { srcDir.listFiles() }

    // Create a file collection using a Callable
    Callable callable = { srcDir.listFiles() } as Callable
    collection = files(callable)

    srcDir = file('src')
    println "Contents of $srcDir.name"
    collection.each { println relativePath(it) }

    srcDir = file('src2')
    println "Contents of $srcDir.name"
    collection.each { println relativePath(it) }
}

> gradle -q list
Contents of src
src/dir1
src/file1.txt
Contents of src2
src2/dir1
src2/dir2

The files() method also accepts FileCollection instances.

A file tree is a hierarchy of files, such as a directory tree. It is represented by the FileTree interface. The FileTree interface extends FileCollection, so you can treat a file tree exactly the same way as you would a file collection. Several objects in Gradle implement the FileTree interface, such as source sets.

One way to obtain a FileTree instance is to use the Project.fileTree() method. This creates a FileTree defined with a base directory, and optionally some Ant-style include and exclude patterns.

// Create a file tree with a base directory
def tree = fileTree(dir: 'src/main')

// Add include and exclude patterns to the tree
tree.include '**/*.java'
tree.exclude '**/Abstract*'

// Create a tree using path
tree = fileTree('src').include('**/*.java')

// Create a tree using closure
tree = fileTree {
    from 'src'
    include '**/*.java'
}

// Create a tree using a map
tree = fileTree(dir: 'src', includes: ['**/*.java'])

You use a file tree in the same way you use a file collection. You can also visit the contents of the tree, and select a subtree using Ant-style patterns:

// Iterate over the contents of a tree
tree.each {File file ->
    println file
}

// Filter a tree
def filtered = tree.matching {
    include 'org/gradle/api/**'
}

// Add trees together
def sum = tree + fileTree(dir: 'src/test')

// Visit the nodes of the tree
tree.visit {node ->
    println "$node.relativePath => $node.file"
}

Many objects in Gradle have properties which accept a logical set of files. For example, the Compile task has a source property, which defines the source files to compile. You can set the value of this property using any of the types supported by the files() method, which we have seen above. This means you can set the property using, for example, a File, String, collection, FileCollection or even a closure. Here are some examples:

compile {
    source = file('src/main/java')
}

compile {
    source = 'src/main/java'
}

compile {
    source = ['src/main/java', '../shared/java']
}

compile {
    source = fileTree(dir: 'src/main/java').matching { include 'org/gradle/api/**' }
}

compile {
    source = {
        fileTree(dir: 'src/main/java') + fileTree(dir: '../shared/java')
    }
}

Usually, there is a method with the same name as the property, which appends to the set of files. Again, this method accepts any of the types supported by the files() method.

compile {
    source 'src/main/java', 'src/main/groovy'
    source file('../shared/java')
    source { file('src/test/').listFiles() }
}

You can use the Copy task to copy files. The copy task allows you to filter the contents of the files as they are copied, and to map the files names.

task copyTask(type: Copy) {
    from 'src/main/webapp'
    into 'build/explodedWar'
    include '**/*.html'
    include '**/*.jsp'
    include 'assets/**'
}

You can also use the Project.copy() method.

task copyMethod << {
    copy {
        from 'src/main/webapp'
        into 'build/explodedWar'
        include '**/*.html'
        include '**/*.jsp'
        include 'assets/**'
    }
}

You can use the command line switches shown in Table 15.2, “Log level command-line options” to choose different log levels. In Table 15.3, “Stacktrace command-line options” you find the command line switches which affect stacktrace logging.

A simple option for logging in your build file is to write messages to standard output. Gradle redirects anything written to standard output to it's logging system at the QUIET log level.

println 'A message which is logged at QUIET level'

Gradle also provides a logger property to a build script, which is an instance of Logger . This interface extends the SLF4J Logger interface and adds a few Gradle specific methods to it. Below is an example of how this is used in the build script:

logger.quiet('An info log message which is always logged.')
logger.error('An error log message.')
logger.warn('A warning log message.')
logger.lifecycle('A lifecycle info log message.')
logger.info('An info log message.')
logger.debug('A debug log message.')
logger.trace('A trace log message.')

You can also hook into Gradle's logging system from within other classes used in the build (classes from the buildSrc directory for example). Simply use an SLF4J logger. You can use this logger the same way as you use the provided logger in the build script.

org.slf4j.Logger slf4jLogger = org.slf4j.LoggerFactory.getLogger('some-logger')
slf4jLogger.info('An info log message logged using SLF4j')

Internally, Gradle uses Ant and Ivy. Both have their own logging system. Gradle redirects their logging output into the Gradle logging system. There is a 1:1 mapping from the Ant/Ivy log levels to the Gradle log levels, except the Ant/Ivy TRACE log level, which is mapped to Gradle DEBUG log level. This means the default Gradle log level will not show any Ant/Ivy output unless it is an error or a warning.

There are many tools out there which still use standard output for logging. By default, Gradle redirects standard output to the QUIET log level and standard error to the ERROR level. This behavior is configurable. Gradle provides a couple of switches for this. To change the log level that standard out is redirected to when your build script gets evaluated, the project object offers a method called Project.captureStandardOutput() .

captureStandardOutput LogLevel.INFO
println 'A message which is logged at INFO level'

To change the log level for standard out during task execution, tasks offer a method also with the name Task.captureStandardOutput() .

task logInfo << {
    println 'A task message which is logged at INFO level'
}
logInfo.captureStandardOutput(LogLevel.INFO)

Tasks and projects also offer a method disableStandardOutputCapture() which causes the standard output to be send to the default standard output. If you need more fine grained control on how standard output is redirected you can use the class StandardOutputLogging .

Gradle also provides integration with the Java Util Logging, Jakarta Commons Logging and Log4j logging toolkits. Any log messages which your build classes write using these logging toolkits will be redirected to Gradle's logging system.

In your build script, a property called ant is provided by Gradle. This is a reference to an AntBuilder instance. This AntBuilder is used to access Ant tasks, types and properties from your build script. There is a very simple mapping from Ant's build.xml format to Groovy, which is explained below.

You execute an Ant task by calling a method on the AntBuilder instance. You use the task name as the method name. For example, you execute the Ant echo task by calling the ant.echo() method. The attributes of the Ant task are passed as Map parameters to the method. Below is an example which executes the echo task. Notice that we can also mix Groovy code and the Ant task markup. This can be extremely powerful.

task hello << {
    String greeting = 'hello from Ant'
    ant.echo(message: greeting)
}

> gradle hello
:hello
[ant:echo] hello from Ant

BUILD SUCCESSFUL

Total time: 1 secs

You pass nested text to an Ant task by passing it as a parameter of the task method call. In this example, we pass the message for the echo task as nested text:

task hello << {
    ant.echo('hello from Ant')
}

> gradle hello
:hello
[ant:echo] hello from Ant

BUILD SUCCESSFUL

Total time: 1 secs

You pass nested elements to an Ant task inside a closure. Nested elements are defined in the same way as tasks, by calling a method with the same name as the element we want to define.

task zip << {
    ant.zip(destfile: 'archive.zip') {
        fileset(dir: 'src') {
            include(name: '**.xml')
            exclude(name: '**.java')
        }
    }
}

You can access Ant types in the same way that you access tasks, using the name of the type as the method name. The method call returns the Ant data type, which you can then use directly in your build script. In the following example, we create an Ant path object, then iterate over the contents of it.

task list << {
    def path = ant.path {
        fileset(dir: 'libs', includes: '*.jar')
    }
    path.list().each {
        println it
    }
}

More information about AntBuilder can be found in 'Groovy in Action' 8.4 or at the Groovy Wiki

task check << {
    ant.taskdef(resource: 'checkstyletask.properties') {
        classpath {
            fileset(dir: 'libs', include: '*.jar')
        }
    }
    ant.checkstyle(config: 'checkstyle.xml') {
        fileset(dir: 'src')
    }
}

configurations {
    checkstyle
}

dependencies {
    checkstyle group: 'checkstyle', name: 'checkstyle', version: '5.0'
}

task check << {
    ant.taskdef(resource: 'checkstyletask.properties', classpath: configurations.checkstyle.asPath)
    ant.checkstyle(config: 'checkstyle.xml') {
        fileset(dir: 'src')
    }
}

You can use the ant.importBuild() method to import an Ant build into your Gradle project. When you import an Ant build, each Ant target is treated as a Gradle task. This means you can manipulate and execute the Ant targets in exactly the same way as Gradle tasks.

ant.importBuild 'build.xml'

<project>
    <target name="hello">
        <echo>Hello, from Ant</echo>
    </target>
</project>

> gradle hello
:hello
[ant:echo] Hello, from Ant

BUILD SUCCESSFUL

Total time: 1 secs

You can add a task which depends on an Ant target:

ant.importBuild 'build.xml'

task intro(dependsOn: hello) << {
    println 'Hello, from Gradle'
}

> gradle intro
:hello
[ant:echo] Hello, from Ant
:intro
Hello, from Gradle

BUILD SUCCESSFUL

Total time: 1 secs

Or, you can add behaviour to an Ant target:

ant.importBuild 'build.xml'

hello << {
    println 'Hello, from Gradle'
}

> gradle hello
:hello
[ant:echo] Hello, from Ant
Hello, from Gradle

BUILD SUCCESSFUL

Total time: 1 secs

It is also possible for an Ant target to depend on a Gradle task:

ant.importBuild 'build.xml'

task intro << {
    println 'Hello, from Gradle'
}

<project>
    <target name="hello" depends="intro">
        <echo>Hello, from Ant</echo>
    </target>
</project>

> gradle hello
:intro
Hello, from Gradle
:hello
[ant:echo] Hello, from Ant

BUILD SUCCESSFUL

Total time: 1 secs

There are several ways to set an Ant property, so that the property can be used by Ant tasks. You can set the property directly on the AntBuilder instance. The Ant properties are also available as a Map which you can change. You can also use the Ant property task. Below are some examples of how to do this.

ant.buildDir = buildDir
ant.properties.buildDir = buildDir
ant.properties['buildDir'] = buildDir
ant.property(name: 'buildDir', location: buildDir)

<echo>buildDir = ${buildDir}</echo>

Many Ant tasks set properties when they execute. There are several ways to get the value of these properties. You can get the property directly from the AntBuilder instance. The Ant properties are also available as a Map. Below are some examples.

<property name="antProp" value="a property defined in an Ant build"/>

println ant.antProp
println ant.properties.antProp
println ant.properties['antProp']

There are several ways to set an Ant reference:

ant.path(id: 'classpath', location: 'libs')
ant.references.classpath = ant.path(location: 'libs')
ant.references['classpath'] = ant.path(location: 'libs')

<path refid="classpath"/>

There are several ways to get an Ant reference:

<path id="antPath" location="libs"/>

println ant.references.antPath
println ant.references['antPath']

The Ant integration is provided by AntBuilder .

If you want to use the plugin for building a Java project, simply include

usePlugin('java')

in your script. That's all. From a technological point of view plugins use just the same operations as you can use from your build scripts. That is, they use the Project and Task API (see Chapter 12, The Project and Task API). The Gradle plugins use this API to:

Let's check this out:

usePlugin 'java'

task show << {
    println relativePath(compileJava.destinationDir)
    println relativePath(processResources.destinationDir)
}

> gradle -q show
build/classes/main
build/classes/main

The Java Plugin adds a compileJava task and a processResources task to the project object which can be accessed by a build script. It has configured the destinationDir property of both of these tasks.

The usePlugin() method either takes a string or a class as an argument. You can write ^[14]

usePlugin(org.gradle.api.plugins.JavaPlugin)

Any class, which implements the Plugin interface, can be used as a plugin. Just pass the class as an argument. You don't need to configure anything else for this. If you want to access a custom plugin via a string identifier, you must inform Gradle about the mapping. You can do this in the file plugin.properties in the top level directory of Gradle. It looks like this for the current release:

#
# Copyright 2009 the original author or authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
base=org.gradle.api.plugins.BasePlugin
java=org.gradle.api.plugins.JavaPlugin
eclipse=org.gradle.api.plugins.EclipsePlugin
groovy=org.gradle.api.plugins.GroovyPlugin
war=org.gradle.api.plugins.WarPlugin
osgi=org.gradle.api.plugins.osgi.OsgiPlugin
jetty=org.gradle.api.plugins.jetty.JettyPlugin
maven=org.gradle.api.plugins.MavenPlugin
project-reports=org.gradle.api.plugins.ProjectReportsPlugin
code-quality=org.gradle.api.plugins.quality.CodeQualityPlugin
scala=org.gradle.api.plugins.scala.ScalaPlugin

If you want to use your own plugins, you must make sure that they are accessible via the build script classpath (see Chapter 34, Organizing Build Logic for more information). To learn more about how to write custom plugins, see Chapter 33, Writing Custom Plugins.

If you use the Java Plugin for example, there are a compileJava and a processResources task for your production code (the same is true for your test code). The default location for the output of those tasks is the directory build/classes/main. What if you want to change this? Let's try:

usePlugin 'java'

task show << {
    processResources.destinationDir = new File(buildDir, 'output')
    println relativePath(processResources.destinationDir)
    println relativePath(compileJava.destinationDir)
}

> gradle -q show
build/output
build/classes/main

Setting the destinationDir of the processResources task had only an effect on the processResources task. Maybe this was what you wanted. But what if you want to change the output directory for all tasks? It would be unfortunate if you had to do this for each task separately.

Gradle's tasks are usually convention aware. A plugin can add a convention object to your project, and map certain values of this convention object to task properties.

usePlugin 'java'

task show << {
    sourceSets.main.classesDir = new File(buildDir, 'output')
    println relativePath(processResources.destinationDir)
    println relativePath(compileJava.destinationDir)
}

> gradle -q show
build/output
build/output

The Java Plugin has added a convention object with a sourceSets property, which we use to set the classes directory. Notice that setting this has changed the destinationDir property of both the processResources and compileJava tasks.

By setting a task attribute explicitly (as we have done in the first example) you overwrite the convention value for this particular task.

Not all of the tasks attributes are mapped to convention object values. It is the decision of the plugin to decide what are the shared properties and then bundle them in a convention object and map them to the tasks.

The properties of a convention object can be accessed as project properties. As shown in the following example, you can also access the convention object explicitly.

usePlugin 'java'

task show << {
    // Access the convention property as a project property
    println relativePath(sourceSets.main.classesDir)
    println relativePath(project.sourceSets.main.classesDir)

    // Access the convention property via the convention object
    println relativePath(convention.sourceSets.main.classesDir)
    println relativePath(convention.plugins.java.sourceSets.main.classesDir)
}

> gradle -q show
build/classes/main
build/classes/main
build/classes/main
build/classes/main

Every project object has a Convention object which is a container for convention objects contributed by the plugins declared for your project. If you simply access or set a property or access a method in your build script, the project object first looks if this is a property of itself. If not, it delegates the request to its convention object. The convention object checks if any of the plugin convention objects can fulfill the request (first wins and the order is not defined). The plugin convention objects also introduce a namespace.

usePlugin('java')
usePlugin('groovy')

Plugins provide tasks, which are glued together via dependsOn relations and a convention object.

The Java plugin introduces the concept of a source set. A source set is a group of source files which are compiled and executed together. These source files may include Java source files and resource files. Other plugins add the ability to include Groovy and Scala source files in a source set. A source set has an associated compile classpath, and runtime classpath.

You might use a source set to define an integration test suite, or for the API classes of your project, or to separate source which needs to be compiled against different Java versions.

The Java plugin defines two standard source sets, called main and test. The main source set contains your production source code, which is compiled and assembled into a JAR file. The test source set contains your unit test source code, which is compiled and executed using JUnit or TestNG.

The Java plugin adds a number of tasks to your project, as shown below.

For each source set you add to the project, the Java plugin adds the following compilation tasks:

The Java plugin also adds a number of tasks which form a lifecycle for the project:

The following diagram shows the relationships between these tasks.

Figure 18.1. Java plugin - tasks

The Java plugin assumes the project layout shown below. None of these directories need exist or have anything in them. The Java plugin will compile whatever it finds, and handles anything which is missing.

sourceSets {
    main {
        java {
            srcDir 'src/java'
        }
        resources {
            srcDir 'src/resources'
        }
    }
}

The Java plugin adds a number of dependency configurations to your project, as shown below. It assigns those configurations to tasks such as compileJava and test. To learn more about configurations see Section 28.3.1, “Configurations” and Section 29.2, “Artifacts and configurations”. Note also that transitive dependencies are disabled by default for the compile configuration. This can be overridden using:

configurations.compile.transitive = true

Figure 18.2. Java plugin - dependency configurations

The Java plugin adds a number of convention properties to the project, shown below. You can use these properties in your build script as though they were properties of the project object (see Section 17.2, “Using the convention object”).

These properties are provided by convention objects of type JavaPluginConvention , BasePluginConvention and ReportingBasePluginConvention .

You can access the source sets of a project using the sourceSets property. This is a container for the project's source sets, of type SourceSetContainer . There is also a sourceSets() method, which you can pass a closure to which configures the source set container. The source set container works pretty much the same way as other containers, such as tasks.

// Various ways to access the main source set
println sourceSets.main.classesDir
println sourceSets['main'].classesDir
sourceSets {
    println main.classesDir
}
sourceSets {
    main {
        println classesDir
    }
}

// Iterate over the source sets
sourceSets.each {SourceSet set ->
    println set.name
}

To configure an existing source set, you simply use one of the above access methods to set the properties of the source set. The properties are described below. Here is an example which configures the main Java and resources directories:

sourceSets {
    main {
        java {
            srcDir 'src/java'
        }
        resources {
            srcDir 'src/resources'
        }
    }
}

To define a new source set, you simply reference it in the sourceSets { } block. When you define a source set, the Java plugin adds a number of tasks which assemble the classes for the source set, as shown in Table 18.2, “Java plugin - source set tasks”. For example, if you add a source set called intTest, the Java plugin adds compileIntTestJava, processIntTestResources and intTestClasses tasks.

sourceSets {
    intTest
}

configurations {
    intTestCompile { extendsFrom compile }
    intTestRuntime { extendsFrom intTestCompile, runtime }
}

sourceSets {
    intTest {
        compileClasspath = sourceSets.main.classes + configurations.intTestCompile
        runtimeClasspath = classes + sourceSets.main.classes + configurations.intTestRuntime
    }
}

task intTestJar(type: Jar) {
    from sourceSets.intTest.classes
}

task intTestJavadoc(type: Javadoc) {
    source sourceSets.intTest.allJava
}

task intTest(type: Test) {
    testClassesDir = sourceSets.intTest.classesDir
    classpath = sourceSets.intTest.runtimeClasspath
}

The javadoc task is an instance of Javadoc . It supports the core javadoc options and the options of the standard doclet described in the reference documentation of the Javadoc executable. For a complete list of supported Javadoc options consult the API documentation of the following classes: CoreJavadocOptions and StandardJavadocDocletOptions .

The clean task is an instance of Clean . It simply removes the directory denoted by its dir property.

The Java plugin uses the Copy task for resource handling. It adds an instance for each source set in the project. You can find out more about the copy task in Section 14.5, “Copying files”.

The Java plugin adds a Compile instance for each source set in the project. The compile task delegates to Ant's javac task to do the compile. You can set most of the properties of the Ant javac task.

The test task is an instance of Test . It executes all unit tests found in the test source set.

Have a look at Test for its complete API. Right now the test results are always in XML-format. The task has a stopAtFailuresOrErrors property to control the behavior when tests are failing. Test always executes all tests. It stops the build afterwards if stopAtFailuresOrErrors is true and there are failing tests or tests that have thrown an uncaught exception.

Per default the tests are run in a forked JVM and the fork is done per test. You can modify this behavior by setting forking to false or set the forkmode to once.

The Test task detects which classes are test classes by inspecting the compiled test classes. By default it scans all .class files. You can set custom includes / excludes, only those classes will be scanned. Depending on the Test framework used (JUnit / TestNG) the test class detection uses different criteria.

When using JUnit, we scan for both JUnit 3 and 4 test classes. If any of the following criteria match, the class is considered to be a JUnit test class. Extend TestCase or GroovyTestCase, Class annotated with RunWith or contain a method annotated with Test (inherited test methods are detected).

When using TestNG, we scan for methods annotated with Test (inherited test methods are detected).

Since 0.6.1 we scan up the inheritance tree into jar files on the test classpath.

In case you don't want to use the test class detection, you can disable it by setting scanForTestClasses to false. This will make the test task only use the includes / excludes to find test classes. If scanForTestClasses is disabled and no include or exclude patterns are specified, the respective defaults are used. For include this is "**/*Tests.class", "**/*Test.class" and the for exclude it is "**/Abstract*.class".

Both JUnit and TestNG are supported through their Ant tasks.

Regarding TestNG reporting, when the test report is disabled the default TestNG listeners are disabled (options.useDefaultListeners is set to false).

The jar task creates a JAR file containing the class files and resources of the project. The JAR file is declared as an artifact in the archives dependency configuration. This means that the JAR is available in the classpath of a dependent project. If you upload your project into a repository, this JAR is declared as part of the dependency descriptor. To learn more about how to work with archives and artifact configurations see Chapter 29, Artifact Management.

If you come from Maven you can have only one library JAR per project. With Gradle you can have as many as you want. You can also add WAR, ZIP and TAR archives to your project. They are all added the same way, so let's look at how you add a ZIP file.

usePlugin 'java'
version = 1.0

task myZip(type: Zip) {
    fileSet(dir: 'somedir')
}

println myZip.archiveName

> gradle -q myZip
zipProject-1.0.zip

This adds a Zip archive task with the name myZip which produces ZIP file zipProject-1.0.zip. It is important to distinguish between the name of the archive task and the name of the archive generated by the archive task. The name of the generated archive file is by default the name of the project with the project version appended. The default name for archives can be changed with the archivesBaseName project property. The name of the archive can also be changed at any time later on.

There are a number of properties which you can set on an archive task. You can, for example, change the name of the archive:

usePlugin 'java'
version = 1.0

task myZip(type: Zip) {
    fileSet(dir: 'somedir')
    baseName = 'customName'
}

println myZip.archiveName

> gradle -q myZip
customName-1.0.zip

You can further customize the archive names:

usePlugin 'java'
archivesBaseName = 'gradle'
version = 1.0

task myZip(type: Zip) {
    appendix = 'wrapper'
    classifier = 'src'
    fileSet(dir: 'somedir')
}

println myZip.archiveName

> gradle -q myZip
gradle-wrapper-1.0-src.zip

Often you will want to publish an archive, so that it is usable from another project. This process is described in Chapter 29, Artifact Management

task zipWithFileSet(type: Zip) {
    fileSet(dir: 'contentDir') {
        include('**/*.txt')
        exclude('**/*.gif')
    }
}

task zipWithFiles(type: Zip) {
    files('path_to_file1', 'path_to_file2')
}

task zipWithZipFileSet(type: Zip) {
    zipFileSet(dir: 'contentDir') {
        include('**/*.txt')
        exclude('**/*.gif')
        prefix = 'myprefix'
    }
}

task tarWithFileSet(type: Tar) {
    tarFileSet(dir: 'contentDir') {
        include('**/*.txt')
        exclude('**/*.gif')
        uid = 'myuid'
    }
}

myZipTask.antDirective {        
   zipgroupfileset(dir: new File(rootDir, 'lib'))    
}

myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz')

myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz') {
    include('**/*.txt')
    exclude('**/*.gif')
    prefix = 'myprefix'
}

myZipTask.mergeGroup('path_to_dir_with_archives') {
    include('**/*.zip')
    exclude('**/*.tar.gz')
}

manifest.mainAttributes("Implementation-Title": "Gradle", "Implementation-Version": version)

manifest.mainAttributes("Implementation-Title": "Gradle", "Implementation-Version": version)
myZipTask.manifest = new GradleManifest(manifest.createManifest())
myZipTask.manifest.mainAttributes(mykey: "myvalue")

metaInf << new FileSet(someDir)

How to upload your archives is described in Chapter 29, Artifact Management.

Gradle comes with a number of tasks for generating eclipse files for your projects.

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 19.1. Groovy plugin - tasks

The Groovy plugin assumes the project layout shown in Table 19.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. ^[17] None of these directories need exist or have anything in them. The Groovy plugin will compile whatever it finds, and handles anything which is missing.

sourceSets {
    main {
        groovy {
            srcDir 'src/groovy'
        }
    }
}

The Groovy plugin adds a dependency configuration called groovy.

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 groovyc compiler and the the groovydoc 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 groovy dependency configuration. Here is an example using the public Maven repository:

repositories {
    mavenCentral()
}

dependencies {
    groovy group: 'org.codehaus.groovy', name: 'groovy', version: '1.6.0'
}

And here is an example using the Groovy JARs checked into the lib directory of the source tree:

repositories {
    flatDir(dirs: file('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')
        }
    }
}

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 (see Section 17.2, “Using the convention 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 instance for each source set in the project. The task type extends the Compile task (see Section 18.10, “CompileJava”). 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.

The Scala plugin adds the following tasks to the project.

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

Figure 20.1. Scala plugin - tasks

The Scala plugin assumes the project layout shown below. All the Scala source directories can contain Scala and Java code. The Java source directories may only contain Java source code. None of these directories need exist or have anything in them. The Scala plugin will compile whatever it finds, and handles anything which is missing.

sourceSets {
    main {
        scala {
            srcDir 'src/scala'
        }
    }
}

The Scala plugin adds a scalaTools configuration, which it uses to locate the Scala tools, such as scalac, to use. You must specify the version of Scala to use. Below is an example.

usePlugin 'scala'

repositories {
    mavenRepo urls: 'http://scala-tools.org/repo-releases/'
}

dependencies {
    // Libraries needed to run the scala tools
    scalaTools 'org.scala-lang:scala-compiler:2.7.6'
    scalaTools 'org.scala-lang:scala-library:2.7.6'

    // Libraries needed for scala api
    compile 'org.scala-lang:scala-library:2.7.6'
}

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

The Scala 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 17.2, “Using the convention object”).

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

The Scala plugin also modifies some source set properties:

The War plugin adds the following tasks to the project.

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

Figure 21.1. War plugin - tasks

The War plugin adds two dependency configurations: providedCompile and providedRuntime. Those configurations have the same scope as the respective compile and runtime configurations, except that they are not added to the WAR archive. It is important to note that those provided configurations work transitively. Let's say you add commons-httpclient:commons-httpclient:3.0 to any of the provided configurations. This dependency has a dependency on commons-codec. This means neither httpclient nor commons-codec is added to your WAR, even if commons-codec were an explicit dependency of your compile configuration. If you don't want this transitive behavior, simply declare your provided dependencies like commons-httpclient:commons-httpclient:3.0@jar.

These properties are provided by a WarPluginConvention convention object.

The default behavior of the War task is to copy the content of src/main/webapp to the root of the archive. Your webapp folder may of course contain a WEB-INF sub-directory, which again may contain a web.xml file. Your compiled classes are compiled to WEB-INF/classes. All the dependencies of the runtime ^[18] configuration are copied to WEB-INF/lib.

Have also a look at War .

Here is an example with the most important customization options:

import org.apache.commons.httpclient.HttpClient
import org.apache.commons.httpclient.methods.GetMethod

group = 'gradle'
version = '1.0'
usePlugin('war')
usePlugin('jetty')

configurations {
   moreLibs
}

repositories {
   flatDir(dirs: "$rootDir/lib")
   mavenCentral()
}

dependencies {
    compile ":compile:1.0"
    providedCompile ":providedCompile:1.0@jar", "javax.servlet:servlet-api:2.5"
    runtime ":runtime:1.0"
    providedRuntime ":providedRuntime:1.0@jar"
    testCompile "junit:junit:3.8.2"
    moreLibs ":otherLib:1.0"
}

war {
    fileSet(dir: file('src/rootContent')) // adds a file-set to the root of the archive
    webInf(dir: file('src/additionalWebInf')) // adds a file-set to the WEB-INF dir.
    additionalLibs(dir: file('additionalLibs')) // adds a file-set to the WEB-INF/lib dir.
    libConfigurations('moreLibs') // adds a configuration to the WEB-INF/lib dir.
    webXml = file('src/someWeb.xml') // copies a file to WEB-INF/web.xml
}

jar.enabled = true

[jettyRun, jettyRunWar]*.daemon = true
stopKey = 'foo'
stopPort = 9451
httpPort = 8163

task runTest(dependsOn: jettyRun) << {
    callServlet()
}

task runWarTest(dependsOn: jettyRunWar) << {
    callServlet()
}

private void callServlet() {
    HttpClient client = new HttpClient()
    GetMethod method = new GetMethod("http://localhost:$httpPort/customised/hello")
    client.executeMethod(method)
    new File(buildDir, "servlet-out.txt").write(method.getResponseBodyAsString())
    jettyStop.execute()
}

Of course one can configure the different file-sets with a closure to define excludes and includes.

If you want to enable the generation of the default jar archive additional to the war archive just type:

jar.enabled = true

EclipseWtp has a default instance with the name eclipseWtp. It generates a .settings/org.eclipse.wst.common.component file.

The Jetty plugin defines the following tasks:

Figure 22.1. Jetty plugin - tasks

The Jetty plugin uses the same layout as the War plugin.

The Jetty plugin does not define any dependency configurations.

The Jetty plugin defines the following convention properties:

These properties are provided by a JettyPluginConvention convention object.

TBD

TBD

TBD

TBD

When used with the Java plugin, the code quality plugin adds the following tasks to the project:

When used with the Groovy plugin, the code quality plugin adds the following tasks to the project:

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

Figure 24.1. Code quality plugin - tasks

The code quality plugin expects the following project layout:

The code quality plugin does not add any dependency configurations.

When used with the Java plugin, the code quality plugin adds the following convention properties to the project:

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

When used with the Groovy plugin, the code quality plugin adds the following convention properties to the project:

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

TBD

TBD

TBD

The OSGi plugin adds an osgi property to every jar task. This osgi property points to an instance of OsgiManifest . Via the OsgiManifest object you can control the generation of the OSGi Manifest of the respective jar. The OSGi plugin assign default values to the OsgiManifest object.

The classes in the classes dir are analyzed regarding there package dependencies and the packages they expose. Based on this the Import-Package and the Export-Package values of the OSGi Manifest are calculated. If the classpath contains jars with an OSGi bundle, the bundle information is used to specify version information for the Import-Package value. Beside the explicit properties of the OsgiManifest object you can add instructions.

configure(jar.osgi) {
    name = 'overwrittenSpecialOsgiName'
    instruction 'Private-Package',
            'org.mycomp.package1',
            'org.mycomp.package2'
    instruction 'Bundle-Vendor', 'MyCompany'
    instruction 'Bundle-Description', 'Platform2: Metrics 2 Measures Framework'
    instruction 'Bundle-DocURL', 'http://www.mycompany.com'
}

The first argument of the instruction call is the key of the property. The other arguments form the value. They are joined by Gradle with the , separator. To learn more about the available instructions have a look at the BND tool.

There are several tasks (presented in Table 26.1, “Eclipse plugin - tasks”) that the Eclipse plugin provides, but you will probably use only eclipse task by executing gradle eclipse.

The Eclipse plugin adds the tasks shown in Table 26.1, “Eclipse plugin - tasks” to a project.

The project report plugin defines the following tasks:

The project report plugin does not require any particular project layout.

The project report plugin does not define any dependency configurations.

The project report defines the following convention properties:

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