Gradle Tutorial : Part 1 : Installation + Setup

To read an overview of this series, refer to the original blog post.

LAST UPDATE : January 21, 2015 : Updated instructions for latest version of Gradle i.e. 2.2.1

In this part of the tutorial, we shall focus on setting up Gradle on our system. While tools like Android Studio do ship with an internal Gradle distribution, our intention here is to understand the tools, its installation, the setup and firing up some basic Gradle commands.

Before we begin with that, if you are still wondering why Gradle is a good choice for build tools, I suggest that you read the following article. Though not essential to read it, it opens up your views as to why companies/developers are flocking to Gradle.

The next few sections will take you through setting up of Gradle on your machine. Gradle requires Java to be present on your machine. So, I shall assume that you are a Java developer and have setup the Java SDK on your machine. 

Download Gradle

At the time of this update, Gradle is in version 2.2.1 and is available for download here.

Just go ahead and download the ZIP file to your machine. You should have a file named gradle-2.2.1-all.zip. Expand it to a folder of your choice.

For e.g. on my machine, I have expanded the same in e:\gradle-2.2.1, such that I have the following sub-folders as shown below:

gradle-2.2.1

 

You might ask why you need a separate installation of Gradle ? This would especially be on your mind if you have already downloaded Android Studio and worked with it. As you know, Android Studio ships with Gradle inside of it and no external installation of Gradle is required.

When we come to the later parts of this tutorial , where we will talk about Android Studio, we will use the Gradle distribution that comes along with it. The focus for all of us in this part and the next few lessons, will be on setting up our own setup of Gradle, running stuff from the command line and being as closed to the bare metal as possible, so that we understand what is going on. Later on, when Android Studio does these things, it will be much easier to understand what is going on ? And you will stop believing that Android Studio is doing some voodoo under the hood.

So for now, do download a separate Gradle installation as instructed and set it up.

 

Environment Settings

The \bin folder of your gradle distribution contains the gradle script file (both Unix and Windows) that you will use to run the gradle command along with various parameters.

Ideally, do the following:

  1. Create a SYSTEM environment variable GRADLE_HOME and point it to the Gradle Installation folder. On my machine, the Gradle installation folder is e:\gradle-2.2.1 and hence I have created a GRADLE_HOME Environment variable that has the value e:\gradle-2.2.1
  2. Add %GRADLE_HOME%\bin to the PATH environment variable. This will allow you to launch gradle command from any directory.

Verify Gradle Setup

To verify our setup, go to the command prompt / terminal and type the following:

gradle -v

This should display information about Gradle / versions and other information as shown below:

------------------------------------------------------------
Gradle 2.2.1
------------------------------------------------------------

Build time: 2014-11-24 09:45:35 UTC
Build number: none
Revision: 6fcb59c06f43a4e6b1bcb401f7686a8601a1fb4a

Groovy: 2.3.6
Ant: Apache Ant(TM) version 1.9.3 compiled on December 23 2013
JVM: 1.7.0_40 (Oracle Corporation 24.0-b56)
OS: Windows 7 6.1 amd64

If you do not see information similar to the one above, check your installation of Gradle and ensure that you have set your PATH variable correctly that contains the direct %GRADLE_HOME%\bin as explained earlier.

A word about Groovy

Any discussion of Gradle is incomplete without Groovy. Groovy as you know is one of the most popular and powerful languages available on the JVM.

Some of the key reasons in favor of Gradle are:

  • It is less verbose
  • It is very flexible
  • It lets you configure and dictate things the way you want

Groovy plays a big role in making the above points happen. Unlike XML that is typically used in Ant and Maven, Groovy is a high level language that not only cuts down on the verbosity with its intuitive and productive syntax but it also gives you full programmatic power to tweak / specify things. All programming language advances like closures etc are available to you. And the build file that you typically ask Gradle to run is actually code that is running for you.

One question that could typically arise is “Do I need to know Groovy?” ? I am tempted to answer you do not. Unless you really want to stray away from convention and do things your own way, then you need to know Groovy because that is where the flexibility of Gradle comes in. But for all purposes, you can use various build.gradle templates that we shall look at and while it contains the Groovy DSL, you need not know much about it or for all you care, not know anything about it. 

So, while you do not have to know Groovy well to understand Gradle, it helps to know that the full power of Groovy is available to you, should you desire that.

Groovy is shipped with default with your Gradle distribution, so you do not have to separately download the same. 

Basic Gradle commands

We have not yet written any source code or build files (Gradle) and we will get to it in while. But try out the following on the command line:

gradle -q help

This command prints out basic help information for Gradle. The -q parameter is just for quiet mode in the console output. It is quite useful as you move along to see less verbose output.

gradle -q tasks

This shows a list of tasks that are already available to you. Give it a shot.

gradle properties

This will list of several properties that are preconfigured for you. You can definitely modify most of these properties in your build files. But it gives you a sense to the heavy duty work that Gradle is setting up for you prior to executing your tasks.

We are not yet going to get to compiling our Java code projects, etc. That is for the next part in this series. We are going to understand how Groovy brings the whole power of programming to Gradle.

To get started, let us first talk about the build.gradle file. This is the standard name used for our build file. All instructions that you need to give to Gradle are contained over here. Over the entire series, we will essentially work with build.gradle file to create / use all sorts of plugins/tasks that will help us compile, build , test and run our Java applications.

For now, let us try out the following (I leave it to you to use a directory of your choice to store the files/code as we move along):

In a folder of your choice, for e.g. example1, create a file named build.gradle.

Put the following as contents of the build.gradle file.

task compileTask << { 
    System.out.println "compiling..." 
}

Now, go to the command line and the folder in which you created the above build.gradle and give the following command

gradle -q tasks

This will list out various tasks that you can perform and you will notice in the output that apart from the standard tasks that you noticed, you also have the task that we created i.e. compileTask 

Other tasks
-----------
compileTask

This brings us to the first concept that our gradle build file is a series of tasks that we specify and which the gradle build system can execute for us. Currently the task that we have specified is named compileTask and what you see is the Groovy code where we just define the task code, where all we are doing is just doing a System.out.println. Remember that Groovy is a high level JVM language.

Now, what if we want to run the compileTask command ?

Before, we get to that, there is one more point to understand. When we fire the gradle command, it looks for a file named build.gradle in the current directory. If it finds one, it uses that. In the above case, since it found one, it determined what tasks are present in the file and added that to the list of tasks that it can perform.

So, what happens if we just type gradle with no other parameters nor do we specify any task to be execute. Let’s try that:

gradle

This will give the following output:

:help
Welcome to Gradle 2.2.1.
To run a build, run gradle <task> ...
To see a list of available tasks, run gradle tasks
To see a list of command-line options, run gradle --help
BUILD SUCCESSFUL
Total time: 2.39 secs

It is clearly telling you that you need to specify the task name when you run it i.e. gradle <task>. Let us do that by giving the following command:

gradle -q compileTask

This will output the text

compiling...

Let us enhance the build.gradle file with another task, so that it looks now like the following:

task compileTask << {
 System.out.println "compiling..." 
}

task buildTask << {
 System.out.println "building..."
}

Now, if you give the following command:

gradle -q tasks

You will find that both the tasks are listed in the otherTasks as shown below:

Other tasks
-----------
buildTask
compileTask

You can now run any of the tasks via gradle compileTask or gradle buildTask and so on.

What if we want to create a default task to be executed, so that if we do not specify the task name, it should execute that.

To do that, modify the build.gradle file as shown below (Add the line in bold):

defaultTasks 'buildTask'

task compileTask << {
  System.out.println "compiling..." 
}

task buildTask << {
  System.out.println "building..."
}

Now, if we simply say gradle -q , it will print the building… string output.

The last part to note here is dependency among tasks. What if we want to make the buildTask dependent on the compileTask, so that if the buildTask is run, it should always run the compileTask first.

To do that, modify the build.gradle file as shown below (Add the text in bold):

defaultTasks 'buildTask'

task compileTask << {
  System.out.println "compiling..." 
}

task buildTask (dependsOn:compileTask) << {
  System.out.println "building..."
}

Now, when you simply invoke gradle -q , it will show the following output:

compiling...
building...

What we have covered in this episode is the very basics of Gradle. Think of your build file as a series of tasks that need to be done. If you are a Java developer and have some experience of the build process (Ant, Maven) , you can easily relate to the fact that to build any stuff, we will need to do things like: compile, build, run tests, package , etc. These are nothing but tasks in Gradle.

We do not necessary have to write all these tasks by hand, though you could if you want to. By using convention that Gradle follows and plugins that work automagically off those conventions, we can perform the same series of steps that are required to build our projects.

There are plugins available in Gradle for e.g. Java plugin, WAR plugin, AppEngine plugin, Android plugin and so on, that expose predefined tasks that you can invoke. We shall see more of that, moving forward in this series.

Next Part

In the next part of the tutorial, we shall look at using Gradle to compile / build our Java projects.

Advertisements

21 thoughts on “Gradle Tutorial : Part 1 : Installation + Setup

  1. In the section “A Word About Groovy” on this page you call Gradle “Gravel”:

    So, while you do not have to know Groovy well to understand Gravel, it helps to know that the full power of Groovy is available to you, should you desire that.

  2. Thanks for taking time and writing this detail tutorial series on Gradle. If you could add Groovy also then it would be great, not deep but detailed enough to customize grade for small tasks.

  3. Great article ! Thanks a lot for this guide.
    A little detail might be helpful. While adding the environment variable GRADLE_HOME, one has to ensure that he/she adds it as a SYSTEM variable and not merely USER variables. In the latter case, appending \bin to GRADLE_HOME may not work.

  4. For people like me, who have an ISSUE WITH ENVIRONMENTAL VARIABLE set up:
    Do not create GRADLE HOME variable just open your PATH (or Path) variable and add the following after last what is there:
    ;E:\gradle-2.6\bin\
    That have worked for me. May it help you too!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s