Writing Build Scripts With Gradle

In the first installment of this series on Gradle, I compared existing Java build tools with Gradle and described Gradle's compelling features. In this article, I show how to write and run Gradle's build scripts.

Installing Gradle

Before installing Gradle, make sure you've already installed the JDK with a version of 1.5 or higher. Even though some operating systems provide you with an out-of-the-box Java installation, make sure you have a valid version installed on your system. To check the JDK version, run java –version.

To get started with Gradle, download the distribution directly from the Gradle homepage. As a beginner to the tool, it makes sense to choose the ZIP file that includes the documentation and a wide range of source code examples to explore. Unzip the downloaded file to a directory of your choice. To reference your Gradle runtime in the shell, you'll need to create the environment variable GRADLE_HOME and add the binaries to your shell's execution path:

• Mac OS X and *nix: To make Gradle available in your shell, add the following two lines to your initialization script (for example, ~/.profile). These instructions assume that you installed Gradle in the directory /opt/gradle:

  export GRADLE_HOME=/opt/gradle
  export PATH=$PATH:$GRADLE_HOME/bin

• Windows: In the dialog environment variable, define the variable GRADLE_HOME and update your path settings (Figure 1).

Figure 1: Updating variable settings on Windows.

You'll verify that Gradle has been installed correctly and is ready to go. To check the version of the installed runtime, issue the command gradle –v in your shell. You should see meta-information about the installation, your JVM, and the operating system. The following example shows the version output of a successful Gradle 1.7 installation.

$ gradle –v

------------------------------------------------------------
Gradle 1.7
------------------------------------------------------------

Build time:   2013-08-06 11:19:56 UTC
Build number: none
Revision:     9a7199efaf72c620b33f9767874f0ebced135d83

Groovy:       1.8.6
Ant:          Apache Ant(TM) version 1.8.4 compiled on May 22 2012
Ivy:          2.2.0
JVM:          1.6.0_51 (Apple Inc. 20.51-b01-457)
OS:           Mac OS X 10.8.4 x86_64

Setting Gradle's JVM Options

Note that like every other Java application, Gradle shares the same JVM options set by the environment variable JAVA_OPTS. If you want to pass arguments specifically to the Gradle runtime, use the environment variable GRADLE_OPTS. Let's say you want to increase the default maximum heap size to 1 GB. You could set it like this:

GRADLE_OPTS="-Xmx1024m"

Although, the preferred way to do that is to add the variable to the Gradle startup script under $GRADLE_HOME/bin.

Now, let's implement a simple build script with Gradle. Even though most of the popular IDEs provide a Gradle plugin, all you need now is your favorite editor. Gradle plugin support exists for IDEs such as IntelliJ IDEA, Eclipse, and NetBeans.

Getting started with Gradle

Every Gradle build starts with a script. The default naming convention for a Gradle build script is build.gradle. When executing the command gradle in a shell, Gradle looks for a file with that exact name. If it can't be located, the runtime will display a help message.

Let's set the lofty goal of creating the typical "Hello world!" example in Gradle. First, create a file called build.gradle. Within that script, define a single atomic piece of work. In Gradle's vocabulary, this is called a task. In this example, the task is called helloWorld. To print the message “Hello world!” make use of Gradle's primary language, Groovy, by adding the println command to the task's action doLast. The method println is Groovy's shorter equivalent to Java's System.out.println:

task helloWorld {
   doLast {
      println 'Hello world!'
   }
}

Give it a spin:

$ gradle –q helloWorld
Hello world!

As expected, you see the output “Hello world!” when running the script. By defining the optional command-line option quiet with –q, you tell Gradle to only output the task's output.

Without knowing it, you already used Gradle's DSL. Tasks and actions are important elements of the language. An action named doLast is almost self-expressive. It's the last action that's executed for a task. Gradle allows for specifying the same logic in a more concise way. The left shift operator << is a shortcut for the action doLast. The following snippet shows a modified version of the first example:

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

Printing "Hello world!" only goes so far. I'll give you a taste of more-advanced features in the example build script shown in Listing One.

task startSession << {
    chant()
}
def chant() {
    ant.echo(message: 'Repeat after me...')
}
3.times {
    task "yayGradle$it" << {
        println 'Gradle rocks'
    }
}
yayGradle0.dependsOn startSession
yayGradle2.dependsOn yayGradle1, yayGradle0
task groupTherapy(dependsOn: yayGradle2)

Listing One: Dynamic task definition and task chaining.

You may not notice it at first, but there's a lot going on in this listing. You introduced the keyword dependsOn to indicate dependencies between tasks. Gradle makes sure that the depended-on task will always be executed before the task that defines the dependency. Under the hood, dependsOn is actually a method of a task.

A feature I talked about in the first installment in this series is Gradle's tight integration with Ant. Because you have full access to Groovy's language features, you can also print your message in a method named chant(). This method can easily be called from your task. Every script is equipped with a property called ant that grants direct access to Ant tasks. In this example, you printed out the message "Repeat after me" using the Ant task echo to start the therapy session.

A nifty feature Gradle provides is the definition of dynamic tasks, which specify their name at runtime. Your script creates three new tasks within a loop using Groovy's times method extension on java.lang.Number. Groovy automatically exposes an implicit variable named it to indicate the loop iteration index. You're using this counter to build the task name. For the first iteration, the task would be called yayGradle0.

Now running gradle groupTherapy results in the following output:

$ gradle groupTherapy
:startSession
[ant:echo] Repeat after me...
:yayGradle0
Gradle rocks
:yayGradle1
Gradle rocks
:yayGradle2
Gradle rocks
:groupTherapy

As shown in Figure 2 Gradle executed the tasks in the correct order. You may have noticed that the example omitted the quiet command-line option, which gives more information on the tasks run.

Figure 2: Task dependency graph.

Now, let's get more accustomed to Gradle's command line.

Using the Command Line

You just executed the tasks helloWorld and groupTherapy on the command line, which is going to be your tool of choice for learning. Even though using an IDE may seem more convenient to newcomers, a deep understanding of Gradle's command-line options and helper tasks will make you more efficient and productive in the long run.