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

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

6. Build variants (build variant version number)

One goal of the new build system is to agree to create different version numbers for the same application.

Here are two basic usage scenarios:

1, different version number of the same application. For example a free version number and a paid professional version number.

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

3, synthesize 1 and 22 kinds of scene.

This goal is to make it possible to generate different apk in the same project, instead of having to use a library project and two and more than two application projects to generate different apk separately.

6.1 Product flavors (different custom products)

A product flavor defines its own definition version number that builds an app from 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 difference between the different version numbers. Although the most project is a lifetime of multiple custom version numbers, they are essentially the same application, so this might 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 version number)

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

Product Flavor does the same thing: the output of the project will stitch together all possible build types and product Flavor (assuming there is a Flavor definition).

Each combination, including build type and product Flavor, is a build variant (build variant version number).

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

The project assumes that undefined flavor will also have a build Variant, simply using 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 the primary configuration for all flavor, and each flavor is able to reset the values of these configurations. In the example above, finally the configuration result will 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 situations where some settings can be set at the same time in build type and product flavor. In such cases, decisions are made in accordance with the principle of the individual.

For example, Signingconfig is a sample of such a property.

Signingconfig agreed 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 used sourceset to build an apk:

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

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

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

* 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.

Finally, similar build type,product flavor can have their own dependencies. For example, suppose you use flavor to generate an ad-based app version number and a paid app version number, where the ad version number may need to be dependent on an ad SDK, but there's another one that doesn't need to be.

    dependencies {        flavor1compile "..."    }

In this example, the Src/flavor1/androidmanifest.xml file may need to declare access to 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 agree to do 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, you will create many other assemble-type tasks. Each is:

1, Assemble<variant Name>: agree to build a Variant version number directly, such as Assembleflavor1debug.

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

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

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

6.6 Testing (TEST)

The test Multi-flavors project is 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/

The same, they can also have their own dependencies:

    dependencies {        androidtestflavor1compile "..."    }

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

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

* Androidtestflavor1debug

* Androidtestflavor2debug

Similarly, each variant version number will also create a corresponding test apk to build the task and install or unload the task:

* Assembleflavor1test

* Installflavor1debug

* Installflavor1test

* Uninstallflavor1debug

* ...

Finally, the HTML report supports merging builds based on flavor.

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

* 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 application may need to create multiple version numbers based on multiple criteria. For example, multi-apk in Google play supports 4 different filters. Each filter that distinguishes between the different apk you create requires that you use a multidimensional product Flavor.

If there is a game that requires a free version number and a paid version number, and you need to use the ABI Filter (ABI) in multi-apk support, the advantage is that no code that modifies the application will move the application to a platform that supports the same ABI, no matter what. This game app requires 3 Abi and two specific app version numbers, so you'll need to generate 6 apk (there's no variant version number generated by calculating different build types).

However, note that in this example, the source code for the paid version number built for three Abi is the same, so it is not a good idea to create 6 flavor to implement.

Instead, use two flavor dimensions and take the initiative to build all possible variant combinations.

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 according to the order of precedence. Each 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], and 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 important (variant naming and prioritization, etc.).

The configuration of each variant version number is determined by several product flavor objects:

* Android.defaultconfig

* An object from the ABI group

* An object from the version group

The sort in flavorgroups determines which flavor is covered, which is important for the resource because the value in one flavor replaces the value defined in the low-priority flavor.

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

Abi > Version > Defaultconfig

The Multi-flavors project has the same extra sourceset, similar to the variant Sourceset, with only a few build Type:

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

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

* Etc ...

This agrees to be customized 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.

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