When we develop a software, we write, compile, test, package, and finally, distribute the code. We can automate these steps by using a build system. The big advantage is that we have a repeatable sequence of steps. The build system will always follow the steps that we have defined, so we can concentrate on writing the actual code and don’t have to worry about the other steps.
Gradle is one such build system. It is a tool for build automation. With Gradle, we can automate compiling, testing, packaging, and deployment of our software or any other types of projects. Gradle is flexible, but has sensible defaults for most projects. This means that we can rely on the defaults if we don’t want something special, but we can still can use the flexibility to adapt a build to certain custom needs.
Gradle is already used by large open source projects such as Spring, Hibernate, and Grails. Enterprise companies such as LinkedIn and Netflix also use Gradle.
In this article, we will explain what Gradle is and how to use it in our development projects.
This Gradle tutorial is an excerpt taken from, ‘Gradle Effective Implementations Guide – Second Edition’ written by Hubert Klein Ikkink.
Declarative builds and convention over configuration
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. As 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 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 will compile. However, 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 also 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. However, we have the flexibility to change these configuration settings if required for our projects.
Support for Ant Tasks and Maven repositories
Gradle supports Ant Tasks and projects. We can import an Ant build and reuse all the tasks. However, we can also write Gradle tasks dependent on Ant Tasks. The integration also applies for 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 that we already have.
Incremental builds in Gradle
With Gradle, we have incremental builds. This means the tasks in a build are only executed if necessary. For example, a task to compile source code will first check whether the sources have changed since the last execution of the task. 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 provided tasks. However, we can also use this for tasks that we write ourselves.
Multi-project builds
Gradle has great support for multi-project builds. A project can simply be dependent on other projects or be a dependency of other projects. We can define a graph of dependencies among projects, and Gradle can resolve these dependencies for us. We have the flexibility to define our project layout as we want.
Gradle has support for partial builds. This means that Gradle will figure out whether a project, which our project depends on, needs to be rebuild or not. If the project needs rebuilding, Gradle will do this before building our own project.
Gradle Wrapper
The Gradle Wrapper allows us to execute Gradle builds even if 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 that the whole team is using the same version. We can also update the Gradle version for the wrapper, and the whole team will use the newer version as the wrapper code is checked in to version control.
Free and open source
Gradle is an open source project and it is licensed under the Apache License (ASL).
Getting started with Gradle
In this section, we will download and install Gradle before writing our first Gradle build script.
Before we install Gradle, we must make sure that we have a Java Development SE Kit (JDK) installed on our computer. Gradle requires JDK 6 or higher. Gradle will use the JDK found on the path of our computer. We can check this by running the following command on the command line:
$ java -version
Although Gradle uses Groovy, we don’t have to install Groovy ourselves. Gradle bundles the Groovy libraries with the distribution and will ignore a Groovy installation that is already available on our computer.
Gradle is available on the Gradle website at http://www.gradle.org/downloads. From this page, we can download the latest release of Gradle. We can also download an older version if we want. We can choose among three different distributions to download. We can download the complete Gradle distribution with binaries, sources, and documentation; or we can only download the binaries; or we can only download the sources.
To get started with Gradle, we will download the standard distribution with the binaries, sources, and documentation. At the time of writing this book, the current release is 2.12.
Installing Gradle
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:
- Binaries in the bin directory
- Documentation with the user guide, Groovy DSL, and API documentation in the doc directory
- A lot of samples in the samples directory
- Source code of Gradle in the src directory
- Supporting libraries for Gradle in the lib directory
- A directory named init.d, where we can store Gradle scripts that need to be executed each time we run Gradle
Once we have unpacked the Gradle distribution to a directory, we can open a command prompt. We go to the directory where we have installed Gradle. To check our installation, we run gradle -v and get an output with the used JDK and library versions of Gradle, as follows:
$ gradle -v
------------------------------------------------------------
Gradle 2.12
------------------------------------------------------------
Build time: 2016-03-14 08:32:03 UTC
Build number: none
Revision: b29fbb64ad6b068cb3f05f7e40dc670472129bc0
Groovy: 2.4.4
Ant: Apache Ant(TM) version 1.9.3 compiled on December23 2013
JVM: 1.8.0_66 (Oracle Corporation 25.66-b17)
OS: Mac OS X 10.11.3 x86_64
Here, we can check whether the displayed version is the same as the distribution version that we have downloaded from the Gradle website.
To run Gradle on our computer, we have to only 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 JAVA_OPTS and GRADLE_OPTS environment variables. JAVA_OPTS is a commonly used environment variable name to pass extra parameters to a Java application. Gradle also uses the GRADLE_OPTS environment variable to pass extra arguments to Gradle. Both environment variables are used, so we can even set them both with different values. This is mostly used to set, for example, an HTTP proxy or extra memory options.
Installing with SKDMAN!
Software Development Kit Manager (SDKMAN!) is a tool to manage versions of software development kits such as Gradle. Once we have installed SKDMAN!, we can simply use the install command and SDKMAN! downloads Gradle and makes sure that it is added to our $PATH variable. SDKMAN! is available for Unix-like systems, such as Linux, Mac OSX, and Cygwin (on Windows).
First, we need to install SDKMAN! with the following command in our shell:
$ curl -s get.sdkman.io | bash
Next, we can install Gradle with the install command:
$ sdk install gradle
Downloading: gradle 2.12
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
0 354 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
100 42.6M 100 42.6M 0 0 1982k 0 0:00:22 0:00:22 --:--:-- 3872k
Installing: gradle 2.12
Done installing!
Do you want gradle 2.12 to be set as default? (Y/n): Y
Setting gradle 2.12 as default.
If we have multiple versions of Gradle, it is very easy to switch between versions with the use command:
$ sdk use gradle 2.12
Using gradle version 2.12 in this shell.
Writing our first build script
We now have a running Gradle installation. It is time to create our first Gradle build script. Gradle uses the concept of projects to define a related set of tasks. A Gradle build can have one or more projects. A project is a very broad concept in Gradle, but it is mostly a set of components that we want to build for our application.
A project has one or more tasks. Tasks are a unit of work that need to be executed by the build. Examples of tasks are compiling source code, packaging class files into a JAR file, running tests, and deploying the application.
We now know a task is a part of a project, so to create our first task, we also create our first Gradle project. We use the gradle command to run a build. Gradle will look for a file named build.gradle in the current directory. This file is the build script for our project. We define our tasks that need to be executed in this build script file.
We create a new build.gradle file and open this in a text editor. We type the following code to define our first Gradle task:
task helloWorld << {
println 'Hello world.'
}
With this code, we will define a helloWorld task. The task will print the words Hello world. to the console. The println is a Groovy method to print text to the console and is basically a shorthand version of the System.out.println Java method.
The code between the brackets is a closure. A closure is a code block that can be assigned to a variable or passed to a method. Java doesn’t support closures, but Groovy does. As Gradle uses Groovy to define the build scripts, we can use closures in our build scripts.
The << syntax is, technically speaking, an operator shorthand for the leftShift()method, which actually means add to. Therefore, here we are defining that we want to add the closure (with the println 'Hello world' statement) to our task with the helloWorld name.
First, we save build.gradle, and with the gradle helloWorld command, we execute our build:
$ gradle helloWorld
:helloWorld
Hello world.
BUILD SUCCESSFUL
Total time: 2.384 secs
This build could be faster, please consider using the Gradle Daemon: https://docs.gradle.org/2.12/userguide/gradle_daemon.html
The first line of output shows our line Hello world. Gradle adds some more output such as the fact that the build was successful and the total time of the build. As Gradle runs in the JVM, every time we run a Gradle build, the JVM must be also started. The last line of the output shows a tip that we can use the Gradle daemon to run our builds. The Gradle daemon keeps Gradle running in memory so that we don’t get the penalty of starting the JVM each time we run Gradle. This drastically speeds up the execution of tasks.
We can run the same build again, but only with the output of our task using the Gradle --quiet or -q command-line option. Gradle will suppress all messages except error messages. When we use the --quiet (or -q) option, we get the following output:
$ gradle --quiet helloWorld Hello world.
Understanding the Gradle graphical user interface
Finally, we take a look at the --gui command-line option. With this option, we start a graphical shell for our Gradle builds. Until now, we used the command line to start a task. With the Gradle GUI, we have a graphical overview of the tasks in a project and we can execute them by simply clicking on the mouse.
To start the GUI, we invoke the following command:
$ gradle --gui
A window is opened with a graphical overview of our task tree. We only have one task that one is shown in the task tree, as we can see in the following screenshot:
The output of running a task is shown at the bottom of the window. When we start the GUI for the first time, the tasks task is executed and we see the output in the window.
Task tree
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 the tasks are shown, but we can apply a filter to show or hide certain projects and tasks. The Edit filter button opens a new dialog window where we can define the tasks and properties that are a 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 to execute the task, add it to the favorites, hide it (adds it to the filter), or edit the build file. If we have associated the .gradle extension to a text editor in our operating system, then the editor is opened with the content of the build script. These options can be seen in the following screenshot:
Favorites
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, or if we have opened the Favorites tab, we can select the Add button and manually enter the project and task name that we want to add to our favorites list. We can see the Add Favorite dialog window in the following screenshot:
Command line
On the Command Line tab, we can enter any Gradle command that we normally would enter on the command prompt. The command can be added to Favorites as well. We see the Command Line tab contents in the following image:
Setup
The last tab is the Setup tab. Here, we can change the project directory, which is set to the current directory by default.
With the GUI, we can select the logging level from the Log Level select box with the different log levels. We can choose to debug, info, Lifecycle, and error as log levels. The error log level only shows errors and is the least verbose, while debug is the most verbose log level. The lifecycle log level is the default log level.
Here, we also can set how detailed the exception stack trace information should be. In the Stack Trace Output section, we can choose from the following three options:
- Exceptions Only: This is for only showing the exceptions when they occur, which is the default value
- Standard Stack Trace (-s): This is for showing more stack trace information for the exceptions
- -S): This is for the most verbose stack trace information for exceptions
If we enable the Only Show Output When Error Occurs option, then we only get output from the build process 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 Use Custom Gradle Executor option. 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 and all the options that we can set:
We learned to install Gradle on our computers and write our first Gradle build script with a simple task. We also looked at the Gradle GUI and how we can use it to run Gradle build scripts.
If you’ve enjoyed this post, do check out this book ‘Gradle Effective Implementations Guide – Second Edition‘to know more about how to use Grade for Java Projects.
