Getting started with the Gradle Wrapper

Gradle is a tool that is under constant development, and new versions could potentially break backward compatibility. Using the Gradle Wrapper is a good way to avoid issues and to make sure builds are reproducible.

The Gradle Wrapper provides a batch file on Microsoft Windows and a shell script on other operating systems. When you run the script, the required version of Gradle is downloaded (if it is not present yet) and used automatically for the build. The idea behind this is that every developer or automated system that needs to build the app can just run the wrapper, which will then take care of the rest. This way, it is not required to manually install the correct version of Gradle on a developer machine or build server. Therefore, it is also recommended to add the wrapper files to your version control system.

Running the Gradle Wrapper is not that different from running Gradle directly. You just execute gradlew on Linux and Mac OS X and gradlew.bat on Microsoft Windows, instead of the regular gradle command.

Getting the Gradle Wrapper

For your convenience, every new Android project includes the Gradle Wrapper, so when you create a new project, you do not have to do anything at all to get the necessary files. It is, of course, possible to install Gradle manually on your computer and use it for your project, but the Gradle Wrapper can do the same things and guarantee that the correct version of Gradle is used. There is no good reason not to use the wrapper when working with Gradle outside of Android Studio.

You can check if the Gradle Wrapper is present in your project by navigating to the project folder and running ./gradlew –v from the terminal or gradlew.bat –v from Command Prompt. Running this command displays the version of Gradle and some extra information about your setup. If you are converting an Eclipse project, the wrapper will not be present by default. In this case, it is possible to generate it using Gradle, but you will need to install Gradle first to get the wrapper.

Note

The Gradle download page (http://gradle.org/downloads) has links to binaries and the source code, and it is possible to use a package manager such as Homebrew if you are on Mac OS X. All the instructions for installation are on the installation page (http://gradle.org/installation).

After you have downloaded and installed Gradle and added it to your PATH, create a build.gradle file containing these three lines:

task wrapper(type: Wrapper) {
    gradleVersion = '2.4'
}

After that, run gradle wrapper to generate the wrapper files.

In recent versions of Gradle, you can also run the wrapper task without modifying the build.gradle file, because it is included as a task by default. In that case, you can specify the version with the --gradle-version parameter, like this:

$ gradle wrapper --gradle-version 2.4

If you do not specify a version number, the wrapper is configured to use the Gradle version that the task is executed with.

These are all the files generated by the wrapper task:

myapp/
├── gradlew
├── gradlew.bat
└── gradle/wrapper/
    ├── gradle-wrapper.jar
    └── gradle-wrapper.properties

You can see here that the Gradle Wrapper has three parts:

• A batch file on Microsoft Windows and a shell script on Linux and Mac OS X
• A JAR file that is used by the batch file and shell script
• A properties file

The gradle-wrapper.properties file is the one that contains the configuration and determines what version of Gradle is used:

#Sat May 30 17:41:49 CEST 2015
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-2.4-all.zip

You can change the distribution URL if you want to use a customized Gradle distribution internally. This also means that any app or library that you use could have a different URL for Gradle, so be sure to check whether you can trust the properties before you run the wrapper.

Android Studio is kind enough to display a notification when the Gradle version used in a project is not up to date and will suggest automatically updating it for you. Basically, Android Studio changes the configuration in the gradle-wrapper.properties file and triggers a build, so that the latest version gets downloaded.

Note

Android Studio uses the information in the properties to determine which version of Gradle to use, and it runs the wrapper from the Gradle Wrapper directory inside your project. However, it does not make use of the shell or bash scripts, so you should not customize those.

Running basic build tasks

In the terminal or command prompt, navigate to the project directory and run the Gradle Wrapper with the tasks command:

$ gradlew tasks

This will print out a list of all the available tasks. If you add the --all parameter, you will get a more detailed overview with the dependencies for every task.

Note

On Microsoft Windows, you need to run gradlew.bat, and on Linux and Mac OS X, the full command is ./gradlew. For the sake of brevity, we will just write gradlew throughout this book.

To build the project while you are developing, run the assemble task with the debug configuration:

$ gradlew assembleDebug

This task will create an APK with the debug version of the app. By default, the Android plugin for Gradle saves the APK in the directory MyApp/app/build/outputs/apk.

Tip

Abbreviated task names

To avoid a lot of typing in the terminal, Gradle also provides abbreviated Camel case task names as shortcuts. For example, you can execute assembleDebug by running gradlew assDeb, or even gradlew aD, from the command-line interface.

There is one caveat to this though. It will only work as long as the Camel case abbreviation is unique. As soon as another task has the same abbreviation, this trick does not work anymore for those tasks.

Besides assemble, there are three other basic tasks:

• check runs all the checks, this usually means running tests on a connected device or emulator
• build triggers both assemble and check
• clean cleans the output of the project

We will discuss these tasks in detail in Chapter 2, Basic Build Customization.