When programming Android applications, you’re most likely to create many files that include numerous lines of source code. The question remains—how does all that source code you just wrote actually become an Android application? The answer—the Gradle build system. Gradle is an open-source tool used to automate the building, running, testing, and packaging of your Android application. Gradle is built directly into Android Studio and you’re also able to run Gradle from the command-line.
Gradle, by itself, is an extremely powerful tool, but when it is combined with Android Studio, you are able to manage complex Android application builds. Gradle is important to learn because when you want to create different builds of the same application—for example, a free version and a paid version—rather than creating two separate Android Studio projects, you can create and manage the building of both applications from within one Android Studio project. In this appendix, you are going to learn about Gradle, the different builds files included with your application, the syntax for scripting your build files, and you will learn more about the options available for including in your build files. By the end of this appendix, you should be comfortable managing a more complex Android application build using Android Studio and Gradle.
Tip
Many of the code examples provided in this appendix are taken from the SimpleGradleBuild
application. The source code for this application is provided for download on the book’s website (http://introductiontoandroid.blogspot.com).
Your Gradle build files are the files named build.gradle
. Depending on how you’ve set up your project, you will have two or more build.gradle
files. One build.gradle
file is for global project build configuration settings and resides in your project root directory. The other build.gradle
file(s) will be found in your application module(s), one per module.
The build.gradle
files are plain text files that rely on Groovy syntax, which is a powerful domain-specific language (DSL) that can be used for creating readable build and automation scripts. You use the Groovy syntax to define how you would like your project built by declaring reserved elements and providing attributes and values. The elements you declare, and the attributes and values you give them, determine how your project and application modules will be built. To learn more about Groovy, see the groovy language website at http://www.groovy-lang.org.
Figure E.1 shows the various ways to access the Gradle build files. On the left, you will notice the Project
view displaying the file system hierarchy of the SimpleGradleBuild
project, and you should notice that the Gradle files are scattered throughout the project directories. On the right, you will notice the Android
symbolic view showing a Gradle Scripts
section that groups all the Gradle files together.
The build.gradle
project file is for defining global build settings that are common to all application modules and subprojects. The file starts with the build script declaration, which defines the repository to use. The repositories available to choose from are J Center, Maven Central, and Ivy.
Note
You define the path to the Android SDK using the ANDROID_HOME
environment variable on your system or by setting the sdk.dir
in the local.properties
file. For example, to set the location of the SDK on Windows using the sdk.dir
setting, simply write this code:
sdk.dir=C:\path\to\sdk
To set the location on Mac OS X, write this code:
sdk.dir=/Applications/Android Studio.app/sdk
Below, you’ll see the top-level project configuration settings of the build.gradle
file of the Simpl e GradleBuild
project.
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:1.3.0'
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
allprojects {
repositories {
jcenter()
}
}
Note
The location for including application modules in Android Studio projects is defined in the settings.gradle
file. To include a module, simply include the named module. For example, to include a module named app
, simply type:
include ':app'
You will spend most of your time marking up the build.gradle
file of your application modules. The module settings are where you configure particular Android SDK settings such as the compileSdkVersion
and buildToolsVersion
. These settings are placed inside the android
element. You also include defaultConfig
settings and buildTypes
. Here is a breakdown of some elements for a module build file:
Applying the Android Gradle Plugin: The first line of your build.gradle
file is used for including the android
plug-in. You do so by including the following line: apply plugin: 'com.android.application'
Android Settings: The compileSdkVersion
and buildToolsVersion
are used for declaring the appropriate version numbers for your requirements.
Default Configurations: The defaultConfig
element is used for providing an applicationId
, minSdkVersion
, targetSdkVersion
, versionCode
, and versionName
Product Flavors: The productFlavors
element is where you define different versions of your application.
Build Types: The buildTypes
element is where you configure ProGuard
settings, application signing, version suffixes, and various other build properties.
Dependencies: The dependencies
element is where you configure local, remote, and module dependencies.
One type of dependency you will most likely use frequently will be the support libraries. The dependencies element is where you would include a particular support library. Later in this appendix, we show you how to include support library dependencies in your project, but first let’s take a look at some important Android support libraries (see Table E.1) that you should be aware of.
The Gradle wrapper can be found in the gradle/wrapper/
directory relative to your project root and includes the gradle-wrapper.jar
file and the gradle-wrapper.properties
file. There is also the gradlew
shell script for Windows, Mac, and Linux, which can be found in your project root. Rather than installing Gradle on your system, you should use the Gradle wrapper included in your project. If you try to build your application using different Gradle wrapper files or a locally installed version of Gradle, your application may not build correctly.
Warning
Never use Gradle wrapper files or Java .jar
files from sources that you do not trust as they could be intended to harm your computer.
You may be wondering if you should include the Gradle wrapper in your source control repository such as GitHub. You should always include Gradle wrapper files to ensure that your application will build properly.
You can edit your build configuration files directly by editing the text or you can use the built-in module setting dialog for configuring your build.gradle
file through user interface controls and form fields. This section covers using Android Studio and the project’s module settings for configuring your build.gradle
file.
Every time you update your Gradle files, Android Studio prompts you to perform a Sync Now
operation to update the configuration changes you’ve made. To avoid hunting down nonexistent bugs in your code, always make sure your files are in sync, otherwise your project may display errors if your build configuration is out of sync. Figure E.2 shows the app
module build.gradle
file requiring project sync and it displays the link for the Sync Now
task.
In order to configure the Android properties of the build.gradle
file using a graphical user interface, you first need to open the Project Structure
dialog. To open the Project Structure
dialog, right-click the project root directory and a menu appears. You will see an Open Module Settings
selection at the bottom of the menu. Click the Open Module Settings
. Figure E.3 shows the menu presented upon right-clicking with the Open Module Settings
option highlighted.
Once the Project Structure
dialog has been opened, you should see the Project Structure
dialog like that shown in Figure E.4. This dialog provides an overview of your Project Structure
and displays, at the far left, any application modules your project has listed under the Modules
section. Make sure a module is selected to edit the build.gradle
file here. The Properties
tab allows you to configure the android
properties of the build.gradle
file.
The code below shows the same options specified as those configured on the Properties
tab of the Project Structure
dialog (Figure E.4):
android {
compileSdkVersion 23
buildToolsVersion "23.0.0"
...
}
When working with the debug version of your application, you are not required to provide a secure certificate for signing your application. If you’re working with the release version of your application, you will need to provide a release key for signing your application. Figure E.5 shows the Signing
tab of the Project Structure
dialog. You can add signing settings on this tab.
The Flavors
tab of the module settings allows you to add, remove, and configure different productFlavors
for creating different versions of your app—for example, both a free and a paid version. You are also able to configure the defaultConfig
options on the Flavors
tab. Figure E.6 shows the Flavors
tab with the defaultConfig
option showing, along with a free
and paid
flavor option.
The code below shows the defaultConfig
, free
, and paid
elements specified as those configured on the Flavors
tab of the Project Structure
dialog:
...
defaultConfig {
applicationId "com.introtoandroid.simplegradlebuild"
minSdkVersion 21
targetSdkVersion 23
versionCode 1
versionName "1.0"
}
...
productFlavors {
free {
applicationId 'com.introtoandroid.simplegradlebuild.free'
versionName '1.0-free'
}
paid {
applicationId 'com.introtoandroid.simplegradlebuild.paid'
versionName '1.0-paid'
}
}
...
The Build Types
tab allows you to add, remove, and configure different build types such as debug
and release
. Figure E.7 shows the debug
build type displaying the available options for configuration.
When editing the Build Types from the Project Structure
dialog, you will notice both a debug
and release
entry, but when editing the build.gradle
file directly, you will not see the debug
entry listed under the buildTypes
section.
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'),
'proguard-rules.pro'
}
}
If you would like to see the debug
entry listed in the buildTypes
section, you need to enter it manually. The following code shows a debug entry:
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'),
'proguard-rules.pro'
}
debug {
debuggable true
}
}
The Dependencies tab allows you to add, remove, reorder, and change the scope of your module dependencies. Figure E.8 shows the Dependencies
tab with a local dependency defined and two module dependencies for including the support-v4
library and the appcompat-v7
library, each with the scope of compile.
If you wanted to add a module library dependency, a dialog appears after clicking the add icon and presents a list of the available module libraries. Figure E.9 shows the Choose Library Dependency
dialog.
Here, you will notice the dependencies
listed in the app
module build.gradle
file. These are the same as those from the Dependencies
tab of the Project Structure
dialog:
dependencies {
compile fileTree(dir: 'libs', include: ['*.jar'])
compile 'com.android.support:support-v4:23.0.0'
compile 'com.android.support:appcompat-v7:23.0.0'
}
In order to be able to build different APK variants, you need to create the appropriate build variant directories and files. Now that you have configured the productFlavors
of free
and paid
, the following steps will allow you to build these variants:
1. Create a free/
and paid/
directory on your app/src/
path.
2. Create a res/
resource directory with a layout/
and values/
subdirectory in both the free/
and paid/
directories you just created.
3. In the layout/
directory of the free
flavor, create an XML file that has the same name of the XML file in your app/src/main/res/layout
directory. In our case, the file is named activity_simple_gradle_build.xml
. For the layout of the free
flavor, create a relative layout with the child TextView
and set the text
attribute to @string/hello_free_world
. Here is the TextView
:
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/hello_free_world" />
Do the same for the paid
flavor, but set the text attribute of the TextView
to @string/hello_paid_world
. Here is the TextView
:
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/hello_paid_world" />
4. In the values/
directory of the free
flavor, create an XML file that has the same name of the XML file in your app/src/main/res/values
directory. Name the file strings.xml
and, for the free
flavor, put the following in the file:
<resources>
<string name="hello_free_world">Hello free world!</string>
</resources>
For the paid
flavor, put the following in the strings.xml
file:
<resources>
<string name="hello_paid_world">Hello paid world!</string>
</resources>
5. Now you’re ready to build the variants. From Android Studio, you are able to open the Build Variants
tab found on the far left toward the bottom of the IDE (see Figure E.10, right). With the Build Variants
tab open you can choose which Build Variant
you would like to build. Select either the freeDebug
or paidDebug
and then build or run your project. After you have built both variants, you will now have an outputs/
folder where the free
and paid
APK variants have been created (see Figure E.10, right-center).
The result of building different APK variants is shown in Figure E.11. The freeDebug
build variant is running on the left on an emulator, and the build process determined the appropriate layout and string file for displaying the text “Hello free world!” The paidDebug
build variant is running on the right on an emulator, and the build process determined the appropriate layout and string file for displaying the text “Hello paid world!”
Android Studio provides a number of different Gradle build tasks that you can execute on your project to verify if the project, its modules, and its source files have been configured properly. Figure E.12 shows the install
tasks that you have available for the app
module. These tasks are specific to the configuration of your project.
You can run these Gradle build tasks by double-clicking a task. You will then see Android Studio executing the task and the results will be displayed similar to what is seen in Figure E.13, where the results of executing the androidDependencies
task are listed in the android
folder of the SimpleGradleBuild
.
This appendix described the Gradle build system and how it is integrated with Android Studio. You learned the basics of Gradle and how to configure different application build types and product flavors. You also learned how to edit the build.gradle
files by using the Groovy syntax with plain text or by using a graphical user interface. You also learned about the various support libraries you can use for module dependencies in your application. You should now be comfortable using Gradle and configuring your project for creating different product flavors and build variants.
1. True or false: The gradlew
and gradlew.bat
files are used for configuring your Gradle settings using plain text.
2. True or false: Gnarly is the name of the domain-specific language used for scripting your Gradle build files.
3. What is the settings.gradle
file used for?
4. Why is it preferable to use the Gradle wrapper rather than using your own installation of Gradle on your system?
5. What element is used for defining the compileSdkVersion
and buildToolsVersion
?
1. Familiarize yourself with the “Gradle Build Language Reference” found here: https://docs.gradle.org/current/dsl.
2. Read the “Signing Your Applications” article found with the online documentation here: http://d.android.com/tools/publishing/app-signing.html.
3. Expand on the SimpleGradleBuild
application to include the signingConfigs
element for both the free
and paid
version release
build.
Android Tools: “Build System Overview”:
http://d.android.com/sdk/installing/studio-build.html
Android Tools: “Configuring Gradle Builds”:
http://d.android.com/tools/building/configuring-gradle.html
Android Tools: “Android Plugin for Gradle”:
http://d.android.com/tools/building/plugin-for-gradle.html
Android Tools: “Manifest Merging”:
http://d.android.com/tools/building/manifest-merge.html
Android Tools: “Building Apps with Over 65K Methods”:
http://d.android.com/tools/building/multidex.html
Android Tools: “Support Library”:
http://d.android.com/tools/support-library/index.html
Android Tools: “Data Binding Guide”:
http://d.android.com/tools/data-binding/guide.html
Android Tools Project Site: “Gradle Plugin User Guide”:
http://tools.android.com/tech-docs/new-build-system/user-guide
“Gradle Build Language Reference”:
https://docs.gradle.org/current/dsl/
“Gradle: The New Android Build System”:
3.148.102.142