Gradle for Android Part 4 (Build Variants)

When you develop an app, you usually have several versions. Most of the time you need a development version to test the app and find out its quality, and then you need a production version. These versions usually have different settings, such as different URL addresses. More likely, you may need a free version and a paid version. Based on the above situation, you need to deal with different versions: development free version, development paid version, production free version, production paid version, and different configurations for different versions, which greatly increases the difficulty of management.

Gradle has some convenient ways to manage these issues. We talked about debug and release versions a long time ago, and now we're going to talk about another concept, different product versions. The build version and the production version can usually be merged. The merged version of the build version and the production version is called a build variant.

In this chapter we will learn about builds, which can make development more efficient, and learn how to use them. Then we will discuss the difference between builds and production versions, and how to merge them. We will explore the signing mechanism, how to sign different variants, etc.

In this chapter, we follow the following rules:

• Build types
• Product flavors
• Build variants
• Signing configurations

Build Version

In the Android plugin for Gradle, a build means defining how an app or dependency library is built. Each build has its own specific aspects, such as whether debug is required, what the application id is, whether unneeded resources are removed, etc. You can define a build using the buildTypes method. For example:

 android {
 buildTypes {
 release {
               minifyEnabled false  
               proguardFiles getDefaultProguardFile
                 ( 'proguard-android.txt' ), 'proguard-rules.pro'  
 }
 }
 }

This file defines that the module is a release version, and then defines the location of proguard. The release version is not the only build version, by default, there is also a debug version. Android studio treats it as the default build version.

Creating your own build

When the default build version is not enough, it is also very easy to create a version. To create a build version, you only need to write your own version in buildTypes. As shown below:

 android {
 buildTypes {
 staging
            applicationIdSuffix ".staging"  
            versionNameSuffix "-staging"  
            buildConfigField "String" , "API_URL" ,
 "\"http://staging.example.com/api\""  
 }
 }
 }

We define a staging version, which defines a new application id, which makes it different from the application ID of the debug and release versions. Assuming you use the default configuration, the application ID will be like this:

• Debug: com.package
• Release: com.package
• Staging: com.package.staging

This means you can install both staging and release builds on your device. The staging build also has its own version number. The buildConfigField defines a new URL address. You don't have to create everything, so the most likely way is to inherit the existing version.

 android {
 buildTypes {
           staging.initWith(buildTypes.debug)
 staging
               applicationIdSuffix ".staging"  
               versionNameSuffix "-staging"  
               debuggable = false  
 }
 }
 }

The initWith() method creates a new version and copies all existing build versions at the same time, similar to inheritance. We can also overwrite all properties of the existing version.

Source sets

When you create a new build, Gradle also creates a new source set. By default, this folder is not created for you automatically, so you need to create it manually.

 app
 └── src
 ├── debug
 │ ├── java
       │ │ └── com.package
 │ │
 │ ├── res
 │ │ └── layout
 │ │ └── activity_main.xml
 │ └── AndroidManifest.xml
 ├── main
 │ ├── java
 │ │ └── com.package
 │ │
 │ ├── res
 └── MainActivity.java
 └── Constants.java
 │ │
 │ │
 │ │
 │ └── AndroidManifest.xml
 ├── staging
 │ ├── java
 │ │ └── com.package
 ├── drawable
 └── layout
 └── activity_main.xml
 │ │
 │ ├── res
 │ │ └── layout
 │ │ └── activity_main.xml
 │ └── AndroidManifest.xml
 └── release
 ├── java
    │ └── com.package
    │ └── Constants.java
    └── AndroidManifest.xml

Note: When you add a Java class, you need to be aware of the following process. When you add CustomLogic.java to the staging version, you can add the same class to the debug and release versions, but not to the main version. If you add it, an exception will be thrown.

When using different source sets, resource files need to be handled in a special way. Drawables and layout files will be overwritten with the same name in main, but resources in values ​​files will not be overwritten. Gradle will merge these resources with the resources in main.

For example, when you create a srings.xml in main:

 <resources>
       <string name = "app_name" >TypesAndFlavors</string>
       <string name = "hello_world" >Hello world!</string>
 </resources>

When you add the rings.xml in your staing build also:

 <resources>
       <string name = "app_name" >TypesAndFlavors STAGING</string>
 </resources>

Then the merged strings.xml will look like this:

 <resources>
       <string name = "app_name" >TypesAndFlavors STAGING</string>
       <string name = "hello_world" >Hello world!</string>
 </resources>

When you create a new build instead of staging, the final strings.xml will be the strings.xml in the main directory.

The manifest is also the same file as the value file. If you create a manifest file for your build, you don't have to copy the manifest file under the main file, all you need to do is add the tag. The Android plugin will merge them for you.

We will discuss merging in more detail in later chapters.

Dependencies

Each build version has its own dependency package, and gradle automatically creates different dependency configurations for each build version. If you want to add a logging framework for the debug version, you can do this:

 dependencies { 
 
   compile fileTree(dir: 'libs' , include: [ '*.jar' ])
   compile 'com.android.support:appcompat-v7:22.2.0'  
   debugCompile 'de.mindpipe.android:android-logging-log4j:1.0.3'  
 }

You can combine different builds with different build configurations, just like this, which makes it possible to have different versions of your dependencies.

product flavors

Unlike build versions, product flavors are used to create different versions of an app. A typical example is that an app has a paid and a free version. Product flavors greatly simplify building different versions of an app based on the same code.

If you're not sure whether you need a new build or product flavors, you should ask yourself whether you need APKs for both internal and external use. If you need a completely new app to ship, completely isolated from previous versions, then you need product flavors. Otherwise you just need a build.

Creating product flavors

Creating product flavors is very easy. You can add code to productFlavors:

 android {
 productFlavors {
 red
             applicationId 'com.gradleforandroid.red'  
 versionCode 3
 }
 blue
             applicationId 'com.gradleforandroid.blue'  
 minSdkVersion 14
 versionCode 4
 }
 }
 }

Product flavors are different from build configurations. Because product flavors have their own ProductFlavor class, just like defaultConfig, this means that all your productFlavors share the same properties.

Source sets

Just like builds, product flavors also have their own code folders. Creating a special flavor is as simple as creating a folder. For example, when you have a production version of blue flavors with a different app icon, the folder should be called blueRelease.

Multiple flavors build variants

In some cases, you may need to create merged versions of some product flavors. For example, client A and client B may both want a free and paid version, both based on the same code, but with different colors, etc. Creating four different flavors means duplicating configuration. The simplest way to merge flavors may be to use flavor dimensions, like this:

 android {
       flavorDimensions "color" , "price"  
 productFlavors {
 red
               flavorDimension "color"  
 }
 blue
               flavorDimension "color"  
 }
 free​
               flavorDimension "price"  
 }
 paid
               flavorDimension "price"  
 }
 }
 }

When you add flavor dimensions, you need to add flavorDimension for each flavor, otherwise an error will be prompted. flavorDimensions defines different dimensions, and of course the order is also important. When you merge two different flavors, they may have the same configuration and resources. For example, in the above example:

• blueFreeDebug and blueFreeRelease
• bluePaidDebug and bluePaidRelease
• redFreeDebug and redFreeRelease
• redPaidDebug and redPaidRelease

Build variants

A build variant is a combination of a build version and a production version. When you create a build version or a production version, new variants are created as well. For example, when you have debug and release versions, and you create red and blue production versions, there will be four variants:

You can find it in the bottom left corner of Android studio, or open it via VIEW | Tool Windows | Build Variants. This view lists all the variants and allows you to switch between them. Changing them will affect the builds you make when you press the Run button.

If you don't have product flavors, then variants simply contain builds. Even if you don't define any builds, Android studio will create a debug version for you by default.

tasks

The android plugin creates different configurations for each variant. A new Android project will have debug and release versions, so you can use assembleDebug and assembleRelease, and of course when you use the assemble command, both are executed. When you add a new build version, a new task is also created. For example:

• assembleBlue uses the blue flavor configuration and assembles both BlueRelease and BlueDebug.
• assembleBlueDebug combines the flavor configuration with the build type configuration, and the flavor settings override the build type settings.

Source sets

Build variants can also have their own resource folders, for example you could have src/blueFreeDebug/java/.

Merging resource files and manifest

Before packaging the app, the Android plugin merges the code in main with the build code. Of course, dependent projects can also provide additional resources, which will also be merged. You may need additional Android permissions for the debug variant. For example, you don't want to declare this permission in main because it may cause some problems, so you can add an additional manifest file in the debug folder, declaring the additional permissions.

The priority of resources and mainfests is as follows:

If a resource is defined in main and in a flavor, the resource in the flavor has a higher priority. In this way, the resource in the flavor folder will be packaged into the apk. The resource declared in the dependent project always has the highest priority.

Creating build variants

Gradle makes it easy to handle build variants.

 android {
 buildTypes {
 debug {
               buildConfigField "String" , "API_URL" ,
 "\"http://test.example.com/api\""  
 }
           staging.initWith(android.buildTypes.debug)
 staging
               buildConfigField "String" , "API_URL" ,
 "\"http://staging.example.com/api\""  
               applicationIdSuffix ".staging"  
 }
 }
 productFlavors {
 red
               applicationId "com.gradleforandroid.red"  
               resValue "color" , "flavor_color" , "#ff0000"  
 }
 blue
               applicationId "com.gradleforandroid.blue"  
               resValue "color" , "flavor_color" , "#0000ff"  
 }
 }
 }

In this example, we created 4 variants, blueDebug, blueStaging, redDebug, and redStaging. Each variant has a different api url and color. For example:

Variant Filters

It is also possible to ignore a variant. This way you can speed up your build when using assemble, so that the tasks you list will not be executed for the variants you don't need. You can use a filter and add the code to your build.gradle as follows:

 android.variantFilter { variant ->
       if(variant.buildType. name .equals( 'release' )) {
           variant.getFlavors().each() { flavor ->
               if (flavor. name .equals( 'blue' )) { variant.setIgnore( true );
 }
 }
 }
 }

In this example, we check:

You can see that blueFreeRelease and bluePaidRelease are excluded, and if you run gradlew tasks you will notice that all the tasks for the above variants are no longer there.

Signature Configuration

Before you release your app, you need to sign your app with a private key. If you have a paid version and a free version, you need different keys to sign different variants. This is the benefit of configuration signatures. Configuration signatures can be defined like this:

 android {
 signingConfigs {
           staging.initWith(signingConfigs.debug)
 release {
               storeFile file( "release.keystore" )
               storePassword "secretpassword"  
               keyAlias ​​"gradleforandroid"  
               keyPassword "secretpassword"  
 }
 }
 }

In this example, we create 2 different signing configurations. The debug configuration is the default one, which uses the public keystore and password, so there is no need to create a signing configuration for the debug version. The staging configuration uses the initWith() method, which copies the other signing configurations. This means that the key for staging and debug is the same.

The release configuration uses storeFile and defines the key alias and password. Of course, this is not a good choice, you need to configure it in the Gradle properties file.

Once you have defined signing configurations, you need to apply them. The build has a property called signingConfig, which you can do like this:

 android {
 buildTypes {
 release {
               signingConfig signingConfigs.release
 }
 }
 }

The above example uses buildTypes, but you may need to generate different validations for each version. You can define it like this:

 android {
 productFlavors {
 blue
               signingConfig signingConfigs.release
 }
 }
 }

Of course, if you define these in flavor, they will be overwritten, so the best way to do it is:

 android {
 buildTypes {
 release {
               productFlavors.red.signingConfig signingConfigs.red
               productFlavors.blue.signingConfig signingConfigs.blue
 }
 }
 }

Summarize

In this chapter, we discussed build and production versions, and how to combine them. This will be a very useful tool when you need different URLs and different keys, and you have the same code and resource files, but with different types and versions, build and production versions will make your life better.

We also talked about signature configurations and how to use them.

In the next chapter, you'll learn about multi-module builds, because this is important when you want to separate your code into a bundle or project, or when you want to include the Android Wear module in your app.