Android Gradle Plugin Guide (v)--build variants (build variant version)

Original address: Http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Build-Variants

6. Build variants (build variant version)

One goal of the new build system is to allow different versions to be created for the same application.

Here are two main usage scenarios:

1. Different versions of the same application. For example a free version and a paid professional version.

2. The same app needs to be packaged into a different apk to publish the Google Play Store. See http://developer.android.com/google/play/publishing/multiple-apks.html for more details.

3, synthesize 1 and 22 kinds of scene.

The goal is to make it possible to generate different apk in the same project, instead of using a library project and two and more than two application projects to generate different apk each way.

6.1 Product flavors (different custom products)

A product flavor defines a custom version of an app built from within the project. A single project can define multiple different flavor at the same time to change the output of the application.

This new design concept is designed to address the very small differences between different versions of the case. While the most projects are built for a lifetime of custom versions, they are essentially the same application, and this may be a better approach than using library projects.

Product flavor needs to be declared in Productflavors this DSL container:

    Android {        ...        .. productflavors {            Flavor1 {...            }            Flavor2 {                ...}}    }

There are two flavor created, named Flavor1 and Flavor2.

Note: The name of the flavor cannot conflict with the existing build type or Androidtest sourceset.

6.2 Build Type + product Flavor = Build Variant (build types + custom products = Build Variant versions)

As mentioned in the previous section, each build type will generate a new apk.

Product Flavor also does these things: the output of the project will stitch together all possible build type and product Flavor (if any Flavor definition exists).

Each combination (containing build type and product Flavor) is a build variant (build Variant version).

For example, in the flavor declaration example above, the default debug and release two build type will generate 4 build variants:

* Flavor1-debug

* Flavor1-release

* Flavor2-debug

* Flavor2-release

If there are no defined flavor in the project, there will also be a build Variant, with only the default flavor and configuration. The default flavor is not named, so the resulting build variant list looks just like the build Type list.

6.3 Product Flavor configuration (product Flavor)

Each flavor is configured by a closure:

    Android {        ...        Defaultconfig {            minsdkversion 8            versioncode        }        productflavors {            Flavor1 {                PackageName] Com.example.flavor1 "                versioncode"            flavor2 {                packagename "Com.example.flavor2"                Minsdkversion}}}    

Note the android.productflavors.* object of the Productflavor type is the same as the type of the android.defaultconfig object. This means that they share the same properties.

Defaultconfig provides a basic configuration for all flavor, and each flavor can reset the values of these configurations. In the example above, the final configuration result would be:

* Flavor1
* PackageName:com.example.flavor1
* Minsdkversion:8
* VERSIONCODE:20
* Flavor2
* PackageName:com.example.flavor2
* MINSDKVERSION:14
* Versioncode:10

Typically, the configuration of Build type overrides other configurations. For example, the packagenamesuffix of Build type is appended to the PackageName of product flavor.

There are also cases where settings can be set in both build type and product flavor. In this case, it is decided on an individual basis.

For example, Signingconfig is an example of this attribute.

Signingconfig allows you to share the same signingconfig for all release packages by setting up android.buildTypes.release.signingConfig . You can also specify their own signingconfig for each release package by setting Android.productflavors.*.signingconfig .

6.4 Sourcesets and Dependencies (source components and dependencies)

Similar to build type, Product flavor provides code and resources through their own sourceset.

The example above will create 4 Sourceset:

* Android.sourceSets.flavor1: Located in src/flavor1/

* Android.sourceSets.flavor2: Located in src/flavor2/

* Android.sourceSets.androidTestFlavor1: Located in src/androidtestflavor1/

* Android.sourceSets.androidTestFlavor2: Located in src/androidtestflavor2/

These sourceset are used to build the APK with the sourceset of the android.sourceSets.main and build type.

The following rules are used to process all the sourceset used to build an apk:

* All source code (SRC/*/JAVA) in multiple folders will be merged to produce an output.

* All manifest files will be merged into one manifest file. Similar to build Type, allows product flavor to have different components and permission declarations.

* All resources used (Android res and assets) follow a priority of build type that overrides the product Flavor and eventually overwrites the resource of main sourceset.

* Each build variant will generate its own R class (or some other source code) based on the resource. The variant is not shared with each other.

Eventually, similar build type,product flavor can have their own dependencies. For example, if you use flavor to generate an ad-based app version and a paid app version, the ad version may need to be dependent on one ad SDK, but the other is not required.

    dependencies {        flavor1compile "..."    }

In this example, the Src/flavor1/androidmanifest.xml file may need to declare permissions to access the network.

Each variant also creates additional Sourceset:

* Android.sourceSets.flavor1Debug: Located in src/flavor1debug/

* Android.sourceSets.flavor1Release: Located in src/flavor1release/

* Android.sourceSets.flavor2Debug: Located in src/flavor2debug/

* Android.sourceSets.flavor2Release: Located in src/flavor2release/

These sourceset have a higher priority than the sourceset of build type, and allow some customization at the variant level.

6.5 Building and tasks (build and Task)

We mentioned earlier that each build type creates its own Assemble<name>task, but the build variant is a combination of build type and product flavor.

When you use product flavor, more assemble-type tasks are created. respectively:

1, Assemble<variant name>: allows you to build a Variant version directly, such as Assembleflavor1debug.

2. Assemble<build type Name>: allows all apk to be built with the specified build type. For example, Assembledebug will build two variant versions of Flavor1debug and Flavor2debug.

3, Assemble<product Flavor name>: allows all apk to be built for the specified Flavor, For example, AssembleFlavor1 will build two variant versions of Flavor1debug and Flavor1release.

In addition, the assemble task constructs a variant version of all possible combinations.

6.6 Testing (TEST)

The Test Multi-flavors project is very similar to testing a simple project.

androidtest Sourceset is used to define all flavor common tests, but each flavor can have its own unique test.

As mentioned earlier, each flavor will create its own test sourceset:

* Android.sourceSets.androidTestFlavor1: Located in src/androidtestflavor1/

* Android.sourceSets.androidTestFlavor2: Located in src/androidtestflavor2/

Similarly, they can have their own dependencies:

    dependencies {        androidtestflavor1compile "..."    }

These tests can be performed through the iconic Devicecheck task of main or the androidtest taskof main (the task is equivalent to a symbolic task when flavor is used).

Each flavor also has their own task to this line of tests:androidtest<variantname>. For example:

* Androidtestflavor1debug

* Androidtestflavor2debug

Similarly, each variant version will also create the corresponding test APK build task and install or unload task:

* Assembleflavor1test

* Installflavor1debug

* Installflavor1test

* Uninstallflavor1debug

* ...

The final HTML report supports merging builds based on flavor.

The following is the path to the test results and report files, the first of which is the result of each flavor version, followed by the merged results:

* build/androidtest-results/flavors/<flavorname>

* build/androidtest-results/all/

* build/reports/androidtests/flavors<flavorname>

* build/reports/androidtests/all/

6.7 Multi-flavor variants

In some cases, an app may need to create multiple versions based on multiple criteria. For example, multi-apk in Google play supports 4 different filters. Each filter that distinguishes between the different apk created requires the ability to use a multidimensional product Flavor.

If you have a game that requires a free version and a paid version, and you need to use the ABI Filter (ABI) in multi-apk support, the advantage is that you can migrate your app to any platform that supports the same ABI without having to change any of the app's code. This game app requires 3 Abi and two specific app versions, so you'll need to generate 6 apk (there's no variant version generated by calculating different build types).

However, note that in this example, the paid version source code that was built for three Abi is the same, so creating 6 flavor is not a good idea.

Instead, two flavor dimensions are used, and all possible variant combinations are built automatically.

The realization of this function is to use flavor Groups. Each group represents a dimension, and flavor is assigned to a specified group.

    Android {        ...        Flavorgroups "Abi", "version"        productflavors {            Freeapp {                flavorgroup "version" ...            }            x86 {                flavorgroup "Abi" ...            }            ...        }    }

The andorid.flavorgroups array defines the group that may be used, in order of precedence. Each of the product flavor is assigned to a group.

In the example above, the product flavor is divided into two groups (that is, two dimensions), the ABI Dimension [X86,arm,mips] and the version dimension [Freeapp,paidapp], plus the default build type has [Debug, Release], this will combine to generate the following build Variant:

* X86-freeapp-debug

* X86-freeapp-release

* Arm-freeapp-debug

* Arm-freeapp-release

* Mips-freeapp-debug

* Mips-freeapp-release

* X86-paidapp-debug

* X86-paidapp-release

* Arm-paidapp-debug

* Arm-paidapp-release

* Mips-paidapp-debug

* Mips-paidapp-release

The group ordering defined in Android.flavorgroups is very important (variant naming and prioritization, etc.).

The configuration of each variant version is determined by a few product flavor objects:

* Android.defaultconfig

* An object from the ABI group

* An object from the version group

Sorting in flavorgroups determines which flavor to overwrite, which is important for resources, because values in one flavor replace those defined in low-priority flavor.

The flavor groups uses the highest priority definition, so the precedence in the example above is:

Abi > Version > Defaultconfig

The Multi-flavors project also has an extra sourceset, similar to the variant Sourceset, except that the build Type is missing:

* Android.sourceSets.x86Freeapp: Located in src/x86freeapp/

* Android.sourceSets.armPaidapp: Located in src/armpaidapp/

* Etc ...

This allows customization at the flavor-combination level. They have a higher priority than the underlying flavor sourceset, but the priority is lower than the sourceset of build type.