Gradle Build – Part 2

In the previous article we created a new project with a Gradle build and looked at couple of tricks for getting the build to run faster. In this article we’ll have a look at the build configuration and understand a little more of what’s going on.

In our top level project we saw a couple of files which control the build: ‘build.gradle” and “settings.gradle”. Let’s start with “build.gradle”:

// Top-level build file where you can 
// add configuration options common 
// to all sub-projects/modules.

There’s actually nothing in there, and the comment explains what this file does: It contains configuration which will get applied to all of the sub-projects and modules within this project.

“settings.gradle” does not contain much more:

include ':GradleTest'

This is rather important, though: It declares that GradleTest is a sub-project and needs to be built as part of the full project build.

So what is the difference between “build.gradle” and “settings.gradle”? In simple terms, “settings.gradle” is used in a project which has children, or sub-projects and tells gradle at build time that these sub-projects must be built. “build.gradle” defines the build itself, and when we define this in a project containing sub-projects and parameters from “build.gradle” get inherited by the sub-projects when they are each built.

So this combination of “build.gradle” and “settings.gradle” simply define a sub-project named “GradleTest” which should be built, so let’s have a look inside this sub-project.

In the “GradleTest” sub-project are a folders named “build” (which contains all of the build artifacts / products during the build), “libs” (which contains third-party libraries – we’ll look at alternatives to this later in the series), and “src” (which contains all of our source code and resources – we’ll look at the structure of this later in the series).

There are also two files: “GradleTest.iml” (which is the Android Studio project file – which we’ll ignore), and “build.gradle” which is the build configuration. So let’s have a look at “build.gradle”:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:0.4'
    }
}
apply plugin: 'android'

dependencies {
    compile files('libs/android-support-v4.jar')
}

android {
    compileSdkVersion 17
    buildToolsVersion "17.0.0"

    defaultConfig {
        minSdkVersion 7
        targetSdkVersion 16
    }
}

Aha! There’s actually something in here! The buildscript section firstly declares that we’ll look for dependencies using Maven Central (if you’re not familiar with this, there’s an explanation here). It also declares the version of the Android Gradle plugin that will be made available within the classpath during the build. It does not mean that we’ll actually use this plugin, it just ensures that it will be available to us.

This “build.gradle” was automatically created for us, but there is actually a slightly newer version of the Android plugin (at the time of writing this is 0.4.3) so we’ll update this to use the latest version by adding a wildcard match. We’ll need to manually change it if we want to use later versions above 0.4.x, but we should automatically get minor updates to 0.4.x which shouldn’t change any APIs, and therefore shouldn’t break our build:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:0.4.+'
    }
}

The next line applies the android plugin. Applying the plugin essentially defines a series of tasks which will be performed in order to perform a complete build. This plugin is part of the Android Gradle tools that we inserted in to the classpath earlier, and will perform all of the necessary steps to actually create an APK from the source materials.

apply plugin: 'android'

Next we add a dependency to the Android Support Library library which has been included in the libs/ folder within the sub-project:

dependencies {
    compile files('libs/android-support-v4.jar')
}

Finally we define the minimum, target, and build SDK levels which will be used, and these correspond to those that we specified when we created the project in the previous article:

android {
    compileSdkVersion 17
    buildToolsVersion "17.0.0"

    defaultConfig {
        minSdkVersion 7
        targetSdkVersion 16
    }
}

There are a couple of things worth mentioning here. Firstly, these files are actually Groovy files. Groovy is a dynamic language which runs on the Java Virtual Machine. It is compatible with Java, so you can actually use Java code within these files, however much what we’re looking at is using features specific to Groovy which is why this isn’t recognisable as Java. A Groovy tutorial is beyond the scope of this tutorial (but there is an article detailing some of the differences between Groovy and Java), but hopefully the meaning of this configuration should be understandable, even if some of the syntax appears a little foreign.

The other thing worth mentioning is that Gradle uses convention over configuration. This means that there are lots of sensible defaults built in, which keep standard configurations rather simple. Later on in the series we’ll look at the structure of the src/ folder and see how we can specify a custom structure, but for now this conforms to the defaults, so we do not need to explicitly configure anything.

So we can see how only a small amount of configuration is required to perform the build: We declare where to try and find the Android Gradle plugin, that we want that plugin to be available in the classpath, that the current project is an “android” project (which is defined within the plugin – although it appears that we are just defining the plugin here, there are actually a couple of plugins within the Android Gradle plugin, and we’ll explore this further later on in the series), requires the Support library, and has specific SDK requirements. The defaults in the plugin do the rest for us!

In the next article we’ll look at some of these defaults, and customise things a little.

The source code for this article is available here.

© 2013 – 2014, Mark Allison. All rights reserved.

Copyright © 2013 Styling Android. All Rights Reserved.
Information about how to reuse or republish this work may be available at http://blog.stylingandroid.com/license-information.