Getting started with Gradle

Did you know that there is a Java build system that does not use angle brackets? More and more projects are using Gradle as an integrated part of their development process. In short, Gradle provides a Groovy DSL for declarative builds based on build conventions. This blog post aims to give you a kickstart if you want to start exploring Gradle yourself by introducing some core concepts and commands.


If you have not used Gradle before, you must install it first (unless someone has already migrated your project to Gradle, but we get to that later). Windows and Linux users can download the latest binaries from Gradle’s download page and unpack the zip. Make sure that you add the GRADLE_HOME/bin folder to your PATH environment variable.

For Mac users, you can use Homebrew to install the latest package:

$ brew install gradle

Verify that the installation works by calling Gradle from your command line:

$ gradle -v
Gradle 1.6

If everything is ok, you will see information about the Gradle version, your JVM, OS and so on. Please consult the installation guide if you have any problem.

Creating a Project

As of Gradle 1.6 that was released the other day, Gradle provides some support for starting a project from scratch. When executed, the incubating build setup plugin generates some tasks that will generate the basic Gradle files:

$ gradle setupBuild


Converting a Maven Project

The setup build plugin can also be used to convert a Maven project to a Gradle project. Let’s try it out by first using a Maven archetype to generate a simple Maven project:

$ mvn archetype:generate

Press enter to accept the suggested archetype, i.e. the maven-archetype-quickstart, and then press enter once more to accept the latest version. I use com.jayway.gradle.example as ‘groupId’, and getting-started as ‘artifactId’. Just keep pressing enter to acknowledge the rest of the suggested default values. Maven generates a simple project with a single class, an accompanying test class and a Maven pom.xml build script. Step into the directory and make sure that it works by executing Maven’s test command:

$ cd getting-started
$ mvn test
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Now, by invoking the setupBuild command the basic content from Maven’s pom.xml file is extracted and converted into Gradle’s corresponding build.gradle file:

$ gradle setupBuild

So far so good, now let’s proceed with some actual Gradle work.

Gradle Tasks

Each Gradle project is associated with a set of tasks. Plugin such as the Gradle Java plugin provide their own tasks, and developers can create their own tasks. Consequently, different projects have different tasks. To see what tasks are available for a particular project, the gradle tasks command is executed:

$ gradle tasks

The available Gradle tasks are listed together with a brief description, e.g.

  • build – Assembles and tests this project.
  • clean – Deletes the build directory.
  • help – Displays a help message
  • tasks – Displays the tasks runnable from root project ‘getting-started’ (some of the displayed tasks may belong to subprojects).
  • test – Runs the unit tests.
  • install – Installs the ‘archives’ artifacts into the local Maven repository.

To execute a task, one simply calls Gradle and the name of the task:

$ gradle test

As a result, Gradle compiles the source file, compiles the test file and executes the test as one would expect. That is actually several different tasks being executed. Underlying tasks will be executed automatically if required.

Gradle Files

When the gradle setupBuild command was executed, a set of files was generated. The build.gradle is the most important of them:

apply plugin: 'java'
apply plugin: 'maven'

group = 'com.jayway.gradle.example'
version = '1.0-SNAPSHOT'

description = 'getting-started'

sourceCompatibility = 1.5
targetCompatibility = 1.5

repositories {
    mavenRepo url: ""

dependencies {
    testCompile group: 'junit', name: 'junit', version:'3.8.1'
  • The first two lines declare the inclusion of two plugins, namely the previously mentioned Java plugin and the Maven plugin.
  • The group and version id was imported from the Maven’s pom.xml together with a generated description.
  • Next, you may wonder why Gradle has specified such old versions of the Java source and Java target files? Looking at the origin pom.xml file does not give any clues, because they were not specified there. The answer resides in Maven’s effective pom (mvn help:effective-pom) and the implicit usage of the maven-compiler-plugin which uses the 1.5 version by default. Depending on your project deployment environment, upgrading to a more recent version is strongly encouraged.
  • The repositories and dependencies have also been included from the Maven script.

Another file that was generated was the settings.gradle file, which is used particularly for multi-project builds.

Lastly, the files gradlew, gradlew.bat, gradle/wrapper/gradle-wrapper.jar and the gradle/wrapper/ have all been added by the Gradle Wrapper. The first two files are command line scripts (for *unix and Windows environment respectively) that are used for executing the jar file with the specified properties, which in turn downloads and installs Gradle automatically. In other words, by adding these files to the version control system, it is possible for new team members and continuous integration system to use Gradle without installing Gradle on beforehand. As a bonus, it provides a way for the team to make sure that everyone is using exactly the same version of Gradle for the project they are developing.

Gradle Plugins

The purpose of the Gradle Plugins is to enrich projects by adding tasks, dependencies, properties and default values.

The Java plugin was briefly mentioned earlier. One of its features is that it adds the same folder structure convention as Maven (src/main/java as root for the production code src/test/java as root for the test code). The external dependency management system is another important feature provided by the Java plugin.

The Maven plugin was also added to the project when it was created. It allows Gradle to interact with Maven based environment, such as installing the binary file to your local Maven repository, uploading it to a remote repository, etc.

Several other plugins are bundled with the Gradle distribution. For example, there is a Jetty plugin, support for development tools such as Eclipse and FindBugs and support for other programming languages such as Scala and Groovy. Additionally, there are a number of external plugins, including the Android Gradle Plugin which one of my colleagues blogged about some time ago.


Mattias Severson

Mattias is a senior software engineer specialized in backend architecture and development with experience of cloud based applications and scalable solutions. He is a clean code proponent who appreciates Agile methodologies and pragmatic Test Driven Development. Mattias has experience from many different environments, including everything between big international projects that last for years and solo, single day jobs. He is open-minded and curious about new technologies. Mattias believes in continuous improvement on a personal level as well as in the projects that he is working on. Additionally, Mattias is a frequent speaker at user groups, companies and conferences.

This Post Has 13 Comments

  1. Tobias Ericsson

    Nice, It’s interesting to see what Gradle can do (better than Maven). So far I have played a little with Gradle in an Android project in AndroidStudio and right now I find the lack of good error-messages when I break something disturbing…

  2. Miklos Krivan

    I was so exited to start to use Gradle but I have to work on Windows and I realized the speed using –daemon was too slow. For the hello world task in daemon mode it takes 7 seconds … this is 1 sec on linux …

    Thx for reply

    1. Mattias Severson

      @Miklos, I am sorry but I cannot help you, I have not used the Gradle Daemon myself, and I am not a Windows user. I suggest that you post a question to the Gradle Forum, unless there already is a good answer.

  3. Renjini

    How to build android using gradle

    1. Mattias Severson

      @Renjini: I have not used the Android Gradle Plugin myself, but the links that I provided (the official user guide on the Android tools site, and the blog post authored by my colleague) should get you started. Additionally, there is also an Android Gradle Quick Start available on Gradleware’s site.

  4. John Pope

    to add Gradle to system path

    echo ‘export PATH=$GRADLE_HOME/bin:$PATH’ >> ~/.profile

    1. Mattias Severson

      If you choose to install using Brew, Gradle is already on your path. From the brew documentation:

      Homebrew installs packages to their own directory and then symlinks their files into /usr/local.

  5. kasunsk

    how to add slf4j in gradle ?

    1. Mattias Severson

      @kasunsk: If you would like to know how to add external dependency to a Gradle project, I believe that you will find the Dependency Management Basics chapter in the Gradle user guide useful.
      On the other hand, if you would like to configure the logging output from your build script execution, I suggest that you look at the Logging chapter instead.

  6. Mathijs

    To convert maven to gradle use the new command.

    “gradle init”


  7. Pand005

    Nice tutorial, here I have a query, for converting maven to gradle I have used “gradle setupBuild” command then build.gradle, settings.gradle, and gradle wrapper files have been generated. But, how to eliminate maven dependencies and maven files like pom.xml, target folder etc as we have converted to Gradle now I don’t want maven in my project. Thanks in advance.

    1. Mattias Severson

      @Pand005: Thank you.
      Basically, you can do two recursive deletions, one that removes all target folders, and on that removes pom.xml files. Several options are available, which method you choose depends on operating system and personal preference.

      1. Start by executing mvn clean to delete the target folders
      2. Next, execute find . -name pom.xml -delete to delete the pom.xml files (works on Linux and OS X)

Leave a Reply