Switching from Maven to Gradle

By Craig Thomas, Tue 10 June 2014, in category Build tools

gradle, maven

During the development of my Chip 8 emulator in Java, I grew increasingly dissatisfied with Maven. While I liked the fact that dependency management was handled in a single spot, the verbose XML format of the POM combined with the quirks of the Maven lifecycle came to be a bit grating. However, for me, the tipping point came when I was trying to build a fat jar.

I want all of my program’s dependencies packaged in a single jar so that I can run a packaged version of the emulator without having to worry about installing anything else on the classpath. This usage case is exactly what the Apache Maven Shade plugin is for. It allows you to construct an "uber-jar" (fat jar), containing all of the other dependencies that your project requires. While it is quite easy to use, I kept getting a lot of warnings while building and packaging that were related to the shade plugin and the creation of the fat jar. To top that off, configuring the Shade plugin meant adding a lot of XML to the POM, most of which felt like a lot of unnecessary cruft (admittedly, I am a Maven novice, so your experiences will probably differ).

Enter Gradle

Gradle is a [Groovy](http://en.wikipedia.org/wiki/Groovy_(programming_language) based project automation tool. Like Maven, Gradle offers dependency management, and can hook into the Maven Central Repository and use Maven plugins. However, Gradle can do much, much more. For example, Gradle contains a wrapper that can be checked into source control. The wrapper can then download Gradle automatically, and build the project. This means that anyone can download and build the project without having to have Gradle installed and configured beforehand. This makes it very nice for things like continuous integration, where you really want to minimize the number of tools needed to build and test the project.

To me however, the main advantage of Gradle was the simple declarative language that it uses to define the project. Gradle does away with XML entirely - the result is a simple and concise looking configuration file. I highly value readability and maintainability, so Gradle felt like a breath of fresh air.

Initializing the Project

Given that my project is rather simple to begin with, I decided to write the new Gradle configuration by hand. For the sake of completeness however, Gradle does offer a command that will attempt to convert a Maven project into a Gradle project. To do that, you need a valid POM file. The command is as simple as:

gradle init --type pom

At this point I should mention that you can get a context sensitive list of tasks that Gradle can perform at any time by typing:

gradle tasks

Given that I wanted to start a new project from scratch to learn more about Gradle, I just created a simple default project definition to start. To do so, I did the following:

gradle init

This created the following files and directories automatically:


These are the interesting artifacts that Gradle creates. In more detail:

All of the files that Gradle creates can be checked into source control, meaning that you can easily version control your dependencies and settings (just like with Maven's POM file).

Defining the Project

The build.gradle file is where the main settings for the project go. To start with, I entered some simple housekeeping information:

apply plugin: 'java'
apply plugin: 'eclipse'

group = 'com.chip8java'
version = '1.0'

description = 'A Chip 8 emulator'

sourceCompatibility = 1.7
targetCompatibility = 1.7

The first two lines refer to plugins that define additional behaviours:

The remainder should be fairly self-explanatory.

Dependency Management

Next, I needed to define the dependencies for my project. I added the following to the build.gradle file:

repositories {

dependencies {
    compile group: 'commons-cli', name: 'commons-cli', version:'20040117.000000'
    testCompile group: 'org.mockito', name: 'mockito-all', version:'1.9.5'
    testCompile group: 'junit', name: 'junit', version:'4.11'

buildscript {
    repositories {

There are three blocks here to note:

Source Locations

I have my files in a slightly different layout for my emulator than what would be normal for a typical project. In the root of the project directory, my source files are located in the src directory. Usually, src/main would be where the main Java sources would go, while src/test would contain unit tests. In my project structure however, I keep my unit tests under the root in the test directory. In order to run unit tests then, I need to tell Gradle where these sources live. This is accomplished with:

sourceSets {
    main {
        java {
            srcDir 'src'
    test {
        java {
            srcDir 'test'

Essentially, sourceSets indicates where my sources are located, with the main Java files located under src. The test files are located in the test directory instead. By doing this, I can run gradle test from the command line, and Gradle knows where the unit test source files are located.

Building a Fat Jar

One of the last tasks I want to perform is to build a fat jar with all of my required dependencies stored in it. This is accomplished with the following:

jar {
    manifest {
        attributes 'Main-Class': 'com.chip8java.emulator.Emulator'

    doFirst {
        from (configurations.runtime.resolve().collect { it.isDirectory() ? it : zipTree(it) }) {
            exclude 'META-INF/MANIFEST.MF'
            exclude 'META-INF/*.SF'
            exclude 'META-INF/*.DSA'
            exclude 'META-INF/*.RSA'

There are two blocks here that are important:

All Together

All of the above sections put together generate a single build.gradle file. Now, to build the project, it is as simple as:

gradle build

To run the unit tests alone, if nothing has changed, you must tell Gradle to clean the unit test build and recompile just the tests:

gradle clean test

And finally, to build the jar:

gradle jar


Switching from Maven to Gradle was quite straightforward. The simplified syntax of the build.gradle file, combined with powerful plugins means less cruft in your configuration files. Additionally, Gradle can use Maven plugins, and can automatically generate skeletons for development projects, convert existing Maven projects into Gradle based projects, and can easily generate the Eclipse project definitions for you.