Gradle is a relatively new build system that is picking up steam. In this post we’ll demonstrate it’s convention over configuration strengths and walk through a simple example.

Gradle follows the convention over configuration model.  As such, if your Java project follows the normal Maven structure, a one line build file will give you all the typical build tasks (aka Ant targets).  As such it’s quick and easy to get started.  The configuration file is a groovy script (more on that later), so it’s completely configurable and your individual project structure can easily be accomodated.  We’ll get to that later…

Getting started

Gradle doesn’t require that each developer, or build machine, have gradle installed.  In fact, the docs say that the preferred way to run gradle is to use the gradle wrapper as opposed to having it installed.  To get a project setup with the gradle wrapper it does require one machine to have gradle installed to setup the wrapper for a particular project.  I’ve taken care of that for you, so all you need to do to follow along is unzip this file.

Once the project is setup and in source control other developers can check it out and start using gradle without requiring gradle to be installed.  For this example we’ll assume that we’ve just unzipped the sample project on a machine without gradle.  For this jump start open a console (or command prompt) and navigate to the location where you unzipped the file noted above.  You should have this:

You can see that there’s a shell script for *nix and Mac and a BAT file for windows.  This is the gradle wrapper.  Note that, for the moment we don’t have any source files — we’ll get to that.  To see what tasks we have available, run gradlew tasks.

The first the thing the wrapper did was download the version of gradle specified in the gradle-wrapper.properties file. Then it ran the tasks task. This displays a list of the default tasks that are available. By using the gradle wrapper everyone running a build for this project will automatically get the same version of gradle without having to keep it updated by hand. To use a different version of gradle, edit the gradle-wrapper.properties file and check it in to source control. Once everyone syncs, the gradle wrapper will download the appropriate version of gradle to their machine and use that to run the builds.

So, let’s do something real with gradle and configure the project as a java project.

Add the following to your build.gradle: apply plugin: 'java'

Now, run gradlew tasks.

There are more tasks!  The question is, if simply adding the java plugin created all these tasks, how does gradle know where to build binaries and where to find source files?  Simple: convention.  If your source tree follows the maven standard it’ll be automatically picked up.  (See the gradle doc, ch. 23.)  Let’s demonstrate.

Create a HelloWorld class (note the src/main/java path standard to Maven).

Run the build gradlew build, and then run the program. Note that the binaries end up in build/classes.

The Build File is code.  Groovy!

Part of the magic of gradle is that the build file is a groovy script.  You can easily add your own tasks if the various plugins aren’t accomplishing what you need. Add the following to your build file:
task showMe << {
    println 'showMe is running'
}
Now, run gradlew showMe:

Fun with IDE’s

Gradle has plugins to integrate with Eclipse and with IntelliJ. These plugins generate the necessary files for each respective IDE. Eclipse users also have the option of using STS from SpringSource. STS has a gradle extension that reads the gradle config and adds dependencies defined there to the project classpath in Eclipse. This is the preferred way of working with gradle within Eclipse.

Let’s demonstrate the IntelliJ (IDEA) plugin. First, add the plugin to gradle:
apply plugin: 'idea'

Then run the build gradlew idea:

This generated all the files needed by Intellij:

Gradle DSL’s

So, how does one handle the configuration of the various plugins to get them to fit your particular setup? Each plugin defines a DSL (domain specific language). These define various groovy objects available and named closures that you can use to over-ride the various behavior and configuration.

Let’s take a look at adding a dependency from maven central. From the gradle DSL we can add the maven repo as follows:

repositories {
    url "http://search.maven.org/"
}

Then, suppose we’re going to use hibernate with our project.  Add a dependency to hibernate as follows:
dependencies {
    compile 'org.hibernate:hibernate-core:3.6.7.Final'
}

Now, when we run the build gradle will download the hibernate jars and include those in the classpath when compiling. If you’re using the Eclipse STS plugin, it’ll automagically recognize this and include this in your classpath within Eclipse. Alternatively, generating the Eclipse or Intellij project files will include the hibernate jars in the project.

Summary

So, we’ve seen how easy it is to get started — all you need is the gradle wrapper.  In fact, you can unzip the sample here into your own project and start using gradle right now.  We’ve also seen how easy it is to add plugins and how the convention over configuration works with them.  We’ve also seen how how the DSL specifies groovy closures that can be used to configure the various tasks, and how to use groovy code to create our own tasks.

For more information, see the gradle DSL specification and the gradle user guide (which has information on all the various plugins).