Gradle Effective Implementation Guide: A must-read for Java developers, this book will bring you bang up to date in the techniques of build automation using Gradle. A fully hands-on approach makes learning natural and entertaining.

Gradle uses a Domain Specific Language (DSL) based on Groovy to declare builds. The DSL provides a flexible language that can be extended by us. Because the DSL is based on Groovy, we can write Groovy code to describe a build and use the power and expressiveness of the Groovy language. Groovy is a language for the Java Virtual Machine (JVM), such as Java and Scala. Groovy makes it easy to work with collections, has closures, and has a lot of useful features. The syntax is closely related to the Java syntax. In fact, we could write a Groovy class file with Java syntax and it would compile. But, using the Groovy syntax makes it easier to express the code intent, and we need less boilerplate code than with Java. To get the most out of Gradle, it is best to learn the basics of the Groovy language, but it is not necessary to start writing Gradle scripts.

Gradle is designed to be a build language and not a rigid framework. The Gradle core itself is written in Java and Groovy. To extend Gradle we can use Java and Groovy to write our custom code. We can even write our custom code in Scala if we want to.

Gradle provides support for Java, Groovy, Scala, Web, and OSGi projects, out of the box. These projects have sensible convention over configuration settings that we probably already use ourselves. But we have the flexibility to change these configuration settings, if needed, in our projects.

Gradle supports Ant tasks and projects. We can import an Ant build and re-use all the tasks. But we can also write Gradle tasks dependent on Ant tasks. The integration also applies to properties, paths, and so on.

Maven and Ivy repositories are supported to publish or fetch dependencies. So, we can continue to use any repository infrastructure we already have.

With Gradle we have incremental builds. This means tasks in a build are only executed if necessary. For example, a task to compile source code will first check whether the sources since the last execution of the task have changed. If the sources have changed, the task is executed, but if the sources haven't changed, the execution of the task is skipped and the task is marked as being up to date.

Gradle supports this mechanism for a lot of the provided tasks. But we can also use this for tasks we write ourselves.

Gradle has great support for multi-project builds. A project can simply be dependent on other projects or be a dependency for other projects. We can define a graph of dependencies between projects, and Gradle can resolve those dependencies for us. We have the flexibility to define our project layout as we want.

Gradle has support for partial builds. This means Gradle will figure out if a project that our project depends on needs to be rebuilt or not. And if the project needs rebuilding, Gradle will do this before building our own project.

The Gradle wrapper allows us to execute Gradle builds, even though Gradle is not installed on a computer. This is a great way to distribute source code and provide the build system with it, so that the source code can be built.

Also, in an enterprise environment, we can have a zero administration way for client computers to build the software. We can use the wrapper to enforce a certain Gradle version to be used, so the whole team is using the same version.

Gradle is an open source project and it is licensed under the Apache Software License(ASL).

Gradle is packaged as a ZIP file for one of the three distributions. So, when we have downloaded the Gradle full distribution ZIP file, we must unzip the file. After unpacking the ZIP file we have the following:

Once we have unpacked the Gradle distribution to a directory, we can open a command prompt. We change the directory to bin, which we extracted from the ZIP file. To check our installation, we run gradle -v and we get output, listing the JDK used and the library versions of Gradle:

$ gradle -v

------------------------------------------------------------
Gradle 1.1
------------------------------------------------------------

Gradle build time: Tuesday, July 31, 2012 1:24:32 PM UTC
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_33 (Apple Inc. 20.8-b03-424)
OS: Mac OS X 10.7.4 x86_64

Here we can check whether the displayed version is the same as the distribution version we have downloaded from the Gradle website.

To run Gradle on our computer we only have to add $GRADLE_HOME/bin to our PATH environment variable. Once we have done that, we can run the gradle command from every directory on our computer.

If we want to add JVM options to Gradle, we can use the environment variables JAVA_OPTS and GRADLE_OPTS. The former is a commonly used environment variable name to pass extra parameters to a Java application. Similarly, Gradle uses the GRADLE_OPTS environment variable to pass extra arguments to Gradle. Both environment variables are used so we can set them both with different values. This is mostly used to set, for example, an HTTP proxy or extra memory options.

Let's look at some of the options in more detail. The options --quiet (or -q), --debug (or -d), --info (or -i), --stacktrace (or -s), and --full-stacktrace (or -S) control the amount of output we see when we execute tasks. To get the most detailed output we use the option --debug (or -d). This option provides a lot of output with information about the steps and classes used to run the build. The output is very verbose, therefore we will not use it much.

To get a better insight into the steps that are executed for our task, we can use the --info (or -i) option. The output is not as verbose as with --debug, but it can give a better understanding of the build steps:

hello-world $ gradle --info helloWorld
Starting Build
Settings evaluated using empty settings file.
Projects loaded. Root project using build file '/Users/gradle/hello-world/build.gradle'.
Included projects: [root project 'hello-world']
Evaluating root project 'hello-world' using build file '/Users/gradle/hello-world/build.gradle'.
All projects evaluated.
Selected primary task 'helloWorld'
Tasks to be executed: [task ':helloWorld']
:helloWorld
Task ':helloWorld' has not declared any outputs, assuming that it is out-of-date.
Hello world.

BUILD SUCCESSFUL

Total time: 1.535 secs

If our build throws exceptions, we can see the stack trace information with the options --stacktrace (or -s) and --full-stacktrace (or -S). The latter option will output the most information and is the most verbose. The options --stacktrace and --full-stracktrace can be combined with the other logging options.

We created our build file with the name build.gradle. This is the default name for a build file. Gradle will look for a file with this name in the current directory, to execute the build. But we can change this with the command-line options --build-file (or -b) and --project-dir (or -p).

Let's run the Gradle command from the parent directory of our current directory:

hello-world $ cd ..
$ gradle --project-dir hello-world -q helloWorld
Hello world.

And we can also rename build.gradle to, for example, hello.build and still execute our build:

hello-world $ mv build.gradle hello.build
hello-world $ gradle --build-file -q helloWorld
Hello world.

With the option --dry-run (or -m), we can run all the tasks without really executing them. When we use the dry run option, we can see which tasks are executed, so we get an insight into which tasks are involved in a certain build scenario. And we don't have to worry if the tasks are actually executed. Gradle builds up a Directed Acyclic Graph (DAG) with all the tasks before any task is executed. The DAG is built so that tasks will be executed in order of dependencies and so that a task is executed only once.

hello-world $ gradle --dry-run helloWorld
:helloWorld SKIPPED

BUILD SUCCESSFUL

Total time: 1.437 secs

We already learned that Gradle is executed in a Java Virtual Machine, and each time we invoke the gradle command, a new Java Virtual Machine is started, the Gradle classes and libraries are loaded, and the build is executed. We can reduce the build execution time if we don't have to load a JVM, Gradle classes, and libraries, each time we execute a build. The command-line option, --daemon, starts a new Java process that will have all Gradle classes and libraries already loaded, and then we execute the build. The next time when we run Gradle with the --daemon option, only the build is executed, because the JVM, with the required Gradle classes and libraries, is already running.

The first time we execute gradle with the --daemon option, the execution speed will not improve, because the Java background process has not started as yet. But the next time around, we will see a major improvement:

hello-world $ gradle --daemon helloWorld
:helloWorld
Hello world.

BUILD SUCCESSFUL

Total time: 0.59 secs

Even though the daemon process has started, we can still run Gradle tasks without using the daemon. We use the command-line option --no-daemon to run a Gradle build without utilizing the daemon:

hello-world $ gradle --no-daemon helloWorld
:helloWorld
Hello world.

BUILD SUCCESSFUL

Total time: 1.496 secs

To stop the daemon process, we use the command-line option --stop:

$ gradle --stop
Stopping daemon.
Gradle daemon stopped.

This will stop the Java background process completely.

To always use the --daemon command-line option, without typing it every time we run the gradle command, we can create an alias—if our operating system supports aliases. For example, on a Unix-based system we can create an alias and then use the alias to run the Gradle build:

hello-world $ alias gradled='gradle --daemon'
hello-world $ gradled helloWorld
:helloWorld
Hello world.

BUILD SUCCESSFUL

Total time: 0.59 secs Instead

Instead of using the --daemon command-line option, we can use the Java system property org.gradle.daemon to enable the daemon. We can add this property to environment variable GRADLE_OPTS, so that it is always used when we run a Gradle build.

hello-world $ export GRADLE_OPTS="-Dorg.gradle.daemon=true"
hello-world $ gradle helloWorld
:helloWorld
Hello world.

BUILD SUCCESSFUL

Total time: 0.707 secs

Gradle also provides the command-line option --profile . This option records the time that certain tasks take to complete. The data is saved in an HTML file in the directory build/reports/profile. We can open this file in a web browser and see the time taken for several phases in the build process. The following image shows the HTML contents of the profile report:

The Task Tree tab shows projects and tasks found in our build project. We can execute a task by double-clicking on the task name.

By default all tasks are shown, but we can apply a filter to show or hide certain projects and tasks. The Filter button opens a new dialog window where we can define which tasks and properties are part of the filter. The Toggle filter button makes the filter active or inactive.

We can also right-click on the project and task names. This opens a context menu where we can choose whether to execute the task, add it to the favorites, hide it (adds it to the filter), or edit the build file. If we click on Edit File, and if the .gradle extension is associated with a text editor in our operating system, the editor is opened with the content of the build script. These options can be seen in the following screenshot:

The Favorites tab stores tasks we want to execute regularly. We can add a task by right-clicking on the task in the Task Tree tab and selecting the Add To Favorites menu option. Alternatively, we can open the Favorites tab, click on the Add button and manually enter the project and task name we want to add to our favorites list. We can see the Add Favorite dialog window in the following screenshot:

On the Command Line tab, we can enter any Gradle command we normally would enter on the command prompt. The command can be added to Favorites as well. We can see the Command Line tab contents in the following screenshot:

The last tab is the Setup tab. Here, we can change the project directory, which is set by default to the current directory.

We learned about the different logging levels as command-line options previously in this chapter. In the GUI, we can select the logging level from the Log Level drop-down box with the different log levels. We can choose one of Debug, Info, Lifecyle, and Error as the log levels. The Error log level only shows errors and is the least verbose, while Debug is the most verbose log level. The Lifecyle log level is the default log level.

Here we can also set how detailed the exception stack trace information should be. In the section Stack Trace Output we can choose between the following three options:

If we enable the option Only Show Output When Errors Occur, we get output from the build process only if the build fails; otherwise we don't get any output.

Finally, we can define a different way to start Gradle for the build, with the option Use Custom Gradle Executor . For example, we can define a different batch or script file with extra setup information to run the build process. The following screenshot shows the Setup tab page along with all the options we can set: