What has Gradle have the Romans ever done for us?

When you click the run button in Android Studio, most of the actual work is done by an external build tool called Gradle. Here are some of the things that Gradle does:

• Locates and downloads the correct versions of any third-party libraries you need.

• Calls the correct build tools in the correct sequence to turn all of your source code and resources into a deployable app.

• Installs and runs your app on an Android device.

• A whole bunch of other stuff, like running tests and checking the quality of your code.

It’s hard to list all of the things that Gradle does because it’s designed to be easily extensible. Unlike other XML-based build tools like Maven or Ant, Gradle is written in a procedural language (Groovy), which is used for both configuring a build and adding extra functionality.

Your project’s Gradle files

Every time you create a new project, Android Studio creates two files called build.gradle. One of these files is in your project folder, and contains a small amount of information that specifies the basic settings of your app, such as what version of Gradle to use, and which online repository:

You will normally only need to change the code in this file if you want to install a third-party plug-in, or need to specify another place that contains downloadable libraries.

Your app’s main Gradle file

The second build.gradle file lives inside the app folder within your project. This file tells Gradle how to build all of the code in your main Android module. It’s where the majority of your application’s properties are set, such as the level of the API that you’re targeting, and the specifics of which external libraries your app will need:

Gradle comes built in to your project

Every time you create a new application, Android Studio includes an install of the Gradle build tool. If you look in the project directory, you will see two files called gradlew and gradlew.bat. These files contains scripts that allow you to build and deploy your app from the command line.

To get more familiar with Gradle, open a command prompt or terminal on your development machine and change into the top-level directory of your project. Then run one of the gradlew scripts with the parameter tasks. Gradle will tell you some of the tasks that it can perform for you:

Let’s take a quick tour of some of the most useful ones.

The check task

The check task performs static analysis on the source code in your application. Think of it as your coding buddy, who at a moment’s notice can scoot through your files looking for coding errors. By default, the check task uses the lint tool to look for common Android programming errors. It will generate a report in app/build/reports/lint-results.html:

The androidDependencies task

For this task, Gradle will automatically pull down any libraries your application requires, and some of those libraries will automatically pull down other libraries, which might pull down other libraries and... well, you get the idea.

Even though your app/build.gradle file might only mention a couple of libraries, your application might need to install many dependent libraries for your app. So it’s sometimes useful to see which libraries your application requires, and why. That’s what the androidDependencies task is for: it displays a tree of all of the libraries in your app:

gradlew <your-task-goes-here>

The real reason that Android apps are commonly built with Gradle is because it’s easily extended. All Gradle files are written in Groovy, which is a general-purpose language designed to be run by Java. That means you can easily add your own custom tasks.

As an example, add the following code to the end of your app/build.gradle file:

task javadoc(type: Javadoc) {
    source = android.sourceSets.main.java.srcDirs
    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
    destinationDir = file("$project.buildDir/javadoc/")
    failOnError false
}

This code creates a new task called javadoc, which generates javadoc for your source code. You can run the task with:

./gradlew javadoc

The generated files will be published in app/build/javadoc:

Gradle plug-ins

As well as writing your own tasks, you can also install Gradle plug-ins. A plug-in can greatly extend your build environment. Want to write Android code in Clojure? Want your build to automatically interact with source control systems like Git? How about spinning up entire servers in Docker and then testing your application on them?

You can do these things, and many, many more by using Gradle plug-ins. For details on what plug-ins are available, see https://plugins.gradle.org.