Android官方技术文档翻译——Gradle 插件用户指南(6)

时间:2020-12-06 16:43:48

没想到翻译这篇《Gradle 插件用户指南》拖了差不多一个月,还跨年了。不过还好,在2号时终于一口气把剩下的给翻译完了(其实那天剩下的也就不到一章)。

今天先发一下第六章,明天再发第七章。

本文译自Android官方技术文档《Gradle Plugin User Guide》,原文地址:http://tools.android.com/tech-docs/new-build-system/user-guide。

翻译不易,转载请注明CSDN博客上的出处:

http://blog.csdn.net/maosidiaoxian/article/details/42386877

前三章见《Android官方技术文档翻译——Gradle 插件用户指南(1-3)》。

第四章见《Android官方技术文档翻译——Gradle 插件用户指南(4)》。

第五章见《Android官方技术文档翻译——Gradle 插件用户指南(5)》。

翻译工作耗时费神,如果你觉得本文翻译得还OK,请点击文末的“顶”,我在精神上会倍受鼓励的,谢谢。翻译如有错讹,敬请指正。

Build Variants

新的构建系统的目标之一是可以创建同一个程序的不同版本。



这里有两个主要的使用场景:
  1. 同一应用程序的不同版本 

    例如,一个应用的免费/演示版本 和“专业”付费版本。
  2. 为了在Google Play Store发布同一个程序的多个APK,而使用不同的包名。

    请参阅 http://developer.android.com/google/play/publishing/multiple-apks.html 以获取更多详细信息。
  3. 综合了1和2 两种情况

这个目标就是要让从同一个项目生成这些不同的APK成为可能,而不是使用一个单独的类库项目和两个以上的应用程序项目中来生成。

Product flavors

一个product flavor 定义了由一个项目构建的应用程序的自定义版本。单个项目可以有不同的flavors来改变生成的应用程序。



这个新概念的设计是为了解决不同版本之间差异很小的情况。如果“这是同一个应用程序吗?”的答案是肯定回答,那么把它转为Library Project的做法也是可以的。



Product flavors使用一个productFlavors DSL 容器来声明: 


android {
    ....

    productFlavors {
        flavor1 {
            ...
        }

        flavor2 {
            ...
        }
    }
}

上面的代码创建了两个flavor,分别是flavor1 和 flavor2。

注意:flavors的名字不能和已经存在的Build Type 的名字或者是 androidTest 的 sourceSet有冲突。

Build Type + Product Flavor = Build Variant

正如我们之前所看到的,每一个Build Type 都会生成一个新的 APK。



Product Flavors 也一样:项目的输出变成 Build Types 和Product Flavors(如果有定义)的所有可能的组合。



每一个 (Build TypeProduct Flavor)组合都称为一个 Build Variant



例如,通过和默认的 debug 和 release Build Types的组合,上面的例子会生成四个 Build Variants:
  • Flavor1 - debug
  • Flavor1 - release
  • Flavor2 - debug
  • Flavor2 - release

即使项目没有定义 flavor,也仍然会有 Build Variants,但是是使用 默认的 flavor或配置。它没有名字,所以使 variants和列表看起来和 Build Types的列表一样。

Product Flavor 配置

每个flavor都通过一个闭包进行配置:


android {
    ...

    defaultConfig {
        minSdkVersion 8
        versionCode 10
    }

    productFlavors {
        flavor1 {
            packageName "com.example.flavor1"
            versionCode 20
        }

        flavor2 {
            packageName "com.example.flavor2"
            minSdkVersion
14
        }
    }
}

请注意, android.productFlavors.*对象的类型是ProductFlavor ,和android.defaultConfig对象的类型一样。这意味着它们共享相同的属性。



defaultConfig提供所有flavor的基本配置,并且每个flavor都可以重写配置里的任何值。在上面的示例中,这个配置最终会是:
  • flavor1
    • packageName: com.example.flavor1
    • minSdkVersion: 8
    • versionCode: 20
  • flavor2
    • packageName: com.example.flavor2
    • minSdkVersion: 14
    • versionCode: 10

通常情况下,Build Type的配置将覆盖其他的配置。例如, Build Type的 packageNameSuffix 将会追加到 Product Flavor的 packageName后面。



也有一些情况是,一个设置可以同时在 Build Type 和 Product Flavor中设置。在这种情况下,就因情况而异了。



例如, signingConfig 就是一个这样的属性。

它既可以通过设置 android.buildTypes.release.signingConfig使所有的relase包都共享相同的SigningConfig,也可以通过单独地设置每一个android.productFlavors.*.signingConfig 对象来让每一个release包使用它们自己的SigningConfig

Sourcesets 和 Dependencies

和 Build Types 一样, Product Flavors 也会通过它们自己的 sourceSets提供源代码和资源。



上面的例子中创建了四个 sourceSets
  • android.sourceSets.flavor1

    位于 src/flavor1/
  • android.sourceSets.flavor2

    位于 src/flavor2/
  • android.sourceSets.androidTestFlavor1

    位于 src/androidTestFlavor1/
  • android.sourceSets.androidTestFlavor2

    位于 src/androidTestFlavor2/

这些sourceSets用于与android.sourceSets.mainBuild Tupe sourset一起构建 apk。 



当处理所有的 sourcesets 来生成单个的 APK 时,下面的规则将会被用到:

  • 多个文件夹里的所有源代码 (src / * / java) 都会一起用于生成一个输出。
  • 所有manifest会被合并为一个manifest。这使得Product Flavors类似于Build Types,可以有不同的组件或权限。
  • 所有的资源(Android res 和 assets)使用的覆盖优先级为Build Type 覆盖 Product Flavor,并最终覆盖 main sourceSet
  • 每一个Build Variant都根据资源生成其自己的R类 (或其他生成的源代码)。variant之间不共享任何内容。

最后,像Build Types一样,Product Flavors可以有它们自己的依赖。例如,如果flavor用于生成广告版的应用程序和付费版的应用程序,其中一个flavor可能要依赖广告的 SDK,而另一个不需要。


dependencies {
    flavor1Compile "..."
}
在这种特殊的情况下,src/flavor1/AndroidManifest.xml文件可能需要包含访问网络的权限。

每一个variant也会创建额外的sourceSets:
  • android.sourceSets.flavor1Debug

    位于 src/flavor1Debug/
  • android.sourceSets.flavor1Release

    位于 src/flavor1Release/
  • android.sourceSets.flavor2Debug

    位于 src/flavor2Debug/
  • android.sourceSets.flavor2Release

    位于 src/flavor2Release/
这些都有比构建类型的sourcesets更高的优先级,并且允许在variant的层次上进行自定义。

Building 和 Tasks

我们在之前已经看到,每个Build Type都会创建自己的assemble<name>任务,但Build VariantsBuild TypeProduct Flavor的一种组合。



当使用Product Flavor 时,会创建更多的assemble类型的任务。它们是:
  1. assemble<Variant 名称>
  2. assemble<Build Type 名称>
  3. assemble<Product Flavor 名称>

#1 允许直接构建一个单一的variant例如assembleFlavor1Debug



#2 允许构建指定的一个Build Type 的所有APK。例如assembleDebug将会构建Flavor1Debug和Flavor2Debug 两个variant。



#3 允许构建一个指定的flavor的所有APK。例如assembleFlavor1将会构建Flavor1Debug和Flavor1Release的两个variant。



assemble 任务将构建所有可能组合的variant。

测试

测试multi-flavors项目与测试简单的项目非常相似。



androidTest sourceset 是所有flavors的共用的测试,而每一个flavor 也都可以有自己的测试。



正如上所述, 用于测试每一个flavor的sourceSets会被创建:

  • android.sourceSets.androidTestFlavor1

    位于 src/androidTestFlavor1/
  • android.sourceSets.androidTestFlavor2

    位于 src/androidTestFlavor2/

同样,它们也可以有其自己的依赖项:

dependencies {
    androidTestFlavor1Compile
"..."
}

这些测试可以通过main deviceCheck锚任务或main androidTest任务(当使用flavors时会被作为锚任务)来完成执行。



每一个flavor都有自己的任务来运行测试: androidTest<VariantName>。例如:
  • androidTestFlavor1Debug
  • androidTestFlavor2Debug

同样,每一个variant也都有对应的测试 APK 构建任务和install/uninstall的任务:

  • assembleFlavor1Test
  • installFlavor1Debug
  • installFlavor1Test
  • uninstallFlavor1Debug
  • ...

最后,HTML 报告支持通过 flavor 合并生成。

测试结果和报告的位置如下,首先为每个flavor版本,然后是聚合之后的版本:

  • build/androidTest-results/flavors/<FlavorName>
  • build/androidTest-results/all/
  • build/reports/androidTests/flavors<FlavorName>
  • build/reports/androidTests/all/

自定义上面的任一路径,将只更改根文件夹,并且仍然会创建每一个flavor的子文件夹和聚合后的结果及报告。

Multi-flavor variants

在某些情况下,人们可能想要基于多个标准创建同一个应用程序的多个版本。 

比如,在Google Play中的多 apk 支持,能支持4个不同的过滤器。创建不同 APK并能在每个过滤器中区分,需要能够使用多维的Product Flavors



以一个游戏为例,假如需要有深圳版本,付费版本,并且想要在多版本支持中使用ABI过滤器。这个应用程序带有三个ABI和两种版本,就需要生成6个APK(不计算由不同的Build Types引入的variants)。

然而,对这三种ABI来说付费版本的代码是相同的,因此创建6个flavors来实现并不是一个好办法。

相反,使用两个维度的flavor,并且variant应该自动构建所有可能的组合。



这个功能是使用Flavor Dimensions来实现的。把 Flavor 分配到指定的维度中
android {
    ...

    flavorDimensions "abi", "version"

    productFlavors {
        freeapp {
            flavorDimension "version"
            ...
        }

        x86 {
            flavorDimension "abi"
            ...
        }
    }
}

android.flavorDimensions数组定义了可能的维度以及顺序。每个定义的Product Flavor被分配到一个维度。



通过以下维度的 Product Flavors [freeapp, paidapp] 和 [x86, arm, mips],以及Build Types的 [debug, release] 的组合,将创建以下的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

android.flavorDimensions定义的维度顺序是非常重要的。



每一个variant都通过几个Product Flavor对象来配置:

  • android.defaultConfig
  • abi 维度中的一个对象
  • version维度中的一个对象

维度的顺序决定了哪一个flavor将覆盖其他的flavor,这对于资源来说非常重要,因为一个flavor的值会替换定义在低优先级的flavor中的值。

flavor 维度首先被定义为具有较高的优先级。所以在这种情况下:

abi > version > defaultConfig


Multi-flavors项目也有额外的 sourcesets,类似于 variant 的 sourcesets,但是没有构建类型:

  • android.sourceSets.x86Freeapp

    位于 src/x86Freeapp/
  • android.sourceSets.armPaidapp

    位于 src/armPaidapp/
  • 等等......
上面这些都允许在flavor-combination的级别上进行自定义。它们有着比基本的 sourcesets更高的优先级,但低于构建类型的sourcesets的优先级。