2022 年 BazelCon 将于 11 月 16 日至 17 日在纽约和线上举办。
立即报名!

Android 规则

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

规则

android_binary

android_binary(name, deps, srcs, assets, assets_dir, compatible_with, crunch_png, custom_package, debug_key, debug_signing_keys, debug_signing_lineage_file, densities, deprecation, dex_shards, dexopts, distribs, enable_data_binding, exec_compatible_with, exec_properties, features, incremental_dexing, instruments, javacopts, key_rotation_min_sdk, licenses, main_dex_list, main_dex_list_opts, main_dex_proguard_specs, manifest, manifest_values, multidex, nocompress_extensions, package_id, plugins, proguard_apply_dictionary, proguard_apply_mapping, proguard_generate_mapping, proguard_specs, resource_configuration_filters, resource_files, restricted_to, shrink_resources, tags, target_compatible_with, testonly, visibility)

生成 Android 应用软件包文件 (.apk)。

隐式输出目标

  • name.apk:使用调试密钥和 zipaligned 签名的 Android 应用软件包文件,可用于开发和调试应用。使用调试密钥签名时,您无法发布应用。
  • name_unsigned.apk:上述文件的未签名版本,可以使用发布密钥进行签名,然后再公开发布。
  • name_deploy.jar:包含此目标的传递闭包的 Java 归档。

    部署 jar 包含类加载器找到的所有类,这些类加载器从头搜索到此目标的运行时类路径。

  • name_proguard.jar:包含对 name_deploy.jar 运行 ProGuard 的结果的 Java 归档。 仅当指定了 proguard_specs 属性时,才会生成此输出。
  • name_proguard.map:在 name_deploy.jar 上运行 ProGuard 的映射文件结果。只有在指定了 proguard_specs 属性且设置了 proguard_generate_mappingshrink_resources 时,才会生成此输出。

示例

Android 规则示例可以在 Bazel 源代码树的 examples/android 目录中找到。

参数

特性
name

Name; required

此定位条件的唯一名称。

deps

List of labels; optional

要链接到二进制目标的其他库的列表。允许的库类型为:android_libraryjava_library(具有 android 限制),以及用于为 Android 目标平台封装或生成 .so 原生库的 cc_library
srcs

List of labels; optional

为创建目标而处理的源文件列表。

编译的是 .java 类型的 srcs 文件。为便于阅读,建议您不要将生成的 .java 源文件的名称放在 srcs 中。请改为将依赖的规则名称放在 srcs 中,具体如下所述。

解压缩并编译 .srcjar 类型的 srcs 文件。(如果您需要生成具有 genrule 或 build 扩展名的一组 .java 文件,这会很有用)。

assets

List of labels; optional

要打包的资源列表。 这通常是 assets 目录下所有文件的 glob。您还可以引用其他软件包中的其他规则(任何生成文件的规则)或导出的文件,只要这些文件位于相应软件包的 assets_dir 目录下。
assets_dir

String; optional

指定 assets 文件的路径。 assetsassets_dir 对用于描述打包的资源,应同时提供这两个属性,或者都不提供。
crunch_png

Boolean; optional; default is True

执行 PNG 处理(或不处理)。这与九宫格处理无关,后者始终完成。这是针对 aapt2 中修复的 aapt bug 的已弃用解决方法。
custom_package

String; optional

将为其生成 Java 源代码的 Java 软件包。默认情况下,从包含相应规则的 BUILD 文件所在的目录中推断出该软件包。您可以指定其他软件包,但强烈建议您不要这样做,因为它会导致与仅在运行时检测到的其他库有关的类路径冲突。
debug_key

Label; optional; default is @bazel_tools//tools/android:debug_keystore

包含调试密钥库的文件,用于为调试 APK 签名。通常,您不希望使用默认密钥以外的密钥,因此应省略此属性。

警告:请不要使用生产密钥,它们应受到严格保护,且不应保留在源代码树中

debug_signing_keys

List of labels; optional

文件列表,用于为调试 APK 签名的调试密钥库。通常情况下,您不需要使用默认密钥以外的键,因此应省略此属性。

警告:请不要使用生产密钥,它们应受到严格保护,且不应保留在源代码树中

debug_signing_lineage_file

Label; optional

包含 debug_signing_keys 签名沿袭的文件。通常情况下,您不需要使用默认密钥以外的键,因此应省略此属性。

警告:请不要使用生产密钥,它们应受到严格保护,且不应保留在源代码树中

densities

List of strings; optional

构建 APK 时要过滤的密度。 这会剥离不会被具有指定屏幕密度的设备加载的光栅可绘制资源,以减小 APK 大小。如果相应的兼容屏幕部分尚未包含超集列表,则也会添加到清单中。
dex_shards

Integer; optional; default is 1

应分解为哪些 dex 分片。这可提高 dex 处理的速度,但会牺牲应用安装和启动时间。二进制文件越大,应使用的分片就越多。从 25 开始,这是一个不错的实验价值。

请注意,每个分片都将在最终应用中产生至少一个 dex。因此,对于版本二进制文件,不建议将其设置为 1。

dexopts

List of strings; optional

dx 工具在生成 class.dex 时的其他命令行标志。 遵循 Make Variable 替换和 Bourne shell 词元化要求。
enable_data_binding

Boolean; optional; default is False

如果为 true,则此规则将在通过 resource_files 属性包含的布局资源中处理数据绑定表达式。如果不进行此设置,数据绑定表达式会导致构建失败。

如需构建具有数据绑定的 Android 应用,您还必须执行以下操作:

  1. 为间接依赖于此规则的所有 Android 规则设置此属性。这是因为依赖项会通过资源合并继承规则的数据绑定表达式。因此,他们还需要使用数据绑定进行构建,以解析这些表达式。
  2. 将数据绑定运行时库的 deps = 条目添加到设置此属性的所有目标。此库的位置取决于您的仓库设置。
incremental_dexing

Integer; optional; nonconfigurable; default is -1

强制在构建时或不使用增量 dex 构建目标,替换默认值和 --incremental_dexing 标志。
instruments

Label; optional

要插桩的 android_binary 目标。

如果设置了此属性,此 android_binary 将被视为插桩测试的测试应用。然后,android_instrumentation_test 目标可以在其 test_app 属性中指定此目标。

javacopts

List of strings; optional

此目标的额外编译器选项。 遵循 Make Variable 替换和 Bourne shell 词元化要求。

这些编译器选项在全局编译器选项之后传递到 javac。

key_rotation_min_sdk

String; optional

设置 APK 轮替签名密钥应该用于生成 APK 签名的最低 Android 平台版本(API 级别)。该 APK 的原始签名密钥将用于所有先前的平台版本。
main_dex_list

Label; optional

文本文件包含类文件名列表。这些类文件定义的类会放在主要 class.dex 文件中。例如:
          android/support/multidex/MultiDex$V19.class
          android/support/multidex/MultiDex.class
          android/support/multidex/MultiDexApplication.class
          com/google/common/base/Objects.class
                    
必须与 multidex="manual_main_dex" 一起使用。
main_dex_list_opts

List of strings; optional

传递给主 dex 列表构建器的命令行选项。使用此选项可影响主 dex 列表中包含的类。
main_dex_proguard_specs

List of labels; optional

用作 Proguard 规范的文件,用于确定必须保留在主 dex 中的类。 仅在 multidex 属性设为 legacy 时才允许。
manifest

Label; required

Android 清单文件的名称,通常为 AndroidManifest.xml。如果定义了 resource_files 或资产,则必须定义。
manifest_values

Dictionary: String -> String; optional

要在清单中替换的值的字典。清单中的任何 ${name} 实例都将被替换为此字典中与名称对应的值。 applicationId、versionCode、versionName、minSdkVersion、targetSdkVersion 和 maxSdkVersion 也将替换清单的相应属性和 uses-sdk 标记。软件包名称将被忽略,并且如果指定,则从 applicationId 设置,或者从清单中设置。将 manifest_merger 设置为旧版时,只有 applicationId、versionCode 和 versionName 会发挥作用。
multidex

String; optional; default is "native"

是否将代码拆分为多个 dex 文件。
可能的值:
  • native:超出 dex 64K 索引限制时,将代码拆分为多个 dex 文件。假设原生平台支持在运行时加载 MultiDex 类。 这仅适用于 Android L 及更高版本
  • legacy:超出 dex 64K 索引限制时,将代码拆分为多个 dex 文件。假设 MultiDex 类通过应用代码加载(即不支持原生平台)。
  • manual_main_dex:超出 dex 64K 索引限制时,将代码拆分为多个 dex 文件。需要使用 main_dex_list 属性在文本文件中提供类列表,才能指定主 dex 文件的内容。
  • off:将所有代码编译到单个 dex 文件中,即使该文件超出了索引限制也是如此。
nocompress_extensions

List of strings; optional

APK 中未压缩的文件扩展名列表。
package_id

Integer; optional; default is 0

要分配给此二进制文件中的资源的软件包 ID。

如需了解详情,请参阅 AAPT2' 的 --package-id 参数。这通常可以(并且应该)保持未设置状态,从而导致出现默认值 127 (0x7F)。

plugins

List of labels; optional

要在编译时运行的 Java 编译器插件。 每当构建此目标时,都会运行插件属性中指定的每个 java_plugin。插件生成的资源会包含在目标的结果 jar 中。
proguard_apply_dictionary

Label; optional

用作 ProGuard 映射的文件。 在混淆过程中重命名类和成员时提取的“字词”文件(以换行符分隔)。
proguard_apply_mapping

Label; optional

用作 ProGuard 映射的文件。 由 proguard_generate_mapping 生成的映射文件,将重复使用,以将相同的映射应用于新 build。
proguard_generate_mapping

Boolean; optional; nonconfigurable; default is False

是否生成 Proguard 映射文件。 仅当指定了 proguard_specs 时,才会生成映射文件。此文件将列出原始名称与经过混淆处理的类、方法和字段名称之间的映射。

警告:如果使用此属性,Proguard 规范不应同时包含 -dontobfuscate-printmapping

proguard_specs

List of labels; optional

将用作 Proguard 规范的文件。 此文件将描述 Proguard 使用的规范集。
resource_configuration_filters

List of strings; optional

资源配置过滤条件列表(例如 &en33;en'),用于将 apk 中的资源限制为 &en33;en' 配置中的资源。如需启用伪本地化,请添加 en_XA 和/或 ar_XB 伪语言区域。
resource_files

List of labels; optional

要打包的资源列表。 这通常是 res 目录下所有文件的 glob
标签也可在此处引用生成的文件(通过 genrule)。唯一的限制是,生成的输出必须与包含的其他任何资源文件位于同一“res”目录下。
shrink_resources

Integer; optional; default is -1

是否执行资源缩减。该二进制文件未使用的资源将从 APK 中移除。仅支持使用本地资源(即 manifestresource_files 属性)的规则,并且需要 ProGuard。其运行方式与 Gradle 资源缩减器 (https://developer.android.com/studio/build/shrink-code.html#shrink-resources) 大致相同。

显著差异:

  • values/ 中的资源以及基于文件的资源都将被移除
  • 默认使用 strict mode
  • 仅 aapt2 支持移除未使用的 ID 资源
如果启用了资源缩减功能,系统还会生成 name_files/resource_shrinker.log,其中详细说明了执行的分析和删除操作。

可能的值:

  • shrink_resources = 1:开启 Android 资源缩减功能
  • shrink_resources = 0:关闭 Android 资源压缩功能
  • shrink_resources = -1:缩减由 --android_resource_shrinking 标志控制。

aar_import

aar_import(name, deps, data, aar, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exports, features, licenses, restricted_to, srcjar, tags, target_compatible_with, testonly, visibility)

此规则允许将 .aar 文件用作 android_libraryandroid_binary 规则的库。

示例

    aar_import(
        name = "google-vr-sdk",
        aar = "gvr-android-sdk/libraries/sdk-common-1.10.0.aar",
    )

    android_binary(
        name = "app",
        manifest = "AndroidManifest.xml",
        srcs = glob(["**.java"]),
        deps = [":google-vr-sdk"],
    )

参数

特性
name

Name; required

此定位条件的唯一名称。

aar

Label; required

要向依赖于此目标的 Android 目标提供的 .aar 文件。
exports

List of labels; optional

要导出到依赖于此规则的规则的目标。请参阅 java_library.exports.
srcjar

Label; optional

包含 AAR 中已编译 JAR 文件源代码的 JAR 文件。

android_library

android_library(name, deps, srcs, data, assets, assets_dir, compatible_with, custom_package, deprecation, distribs, enable_data_binding, exec_compatible_with, exec_properties, exported_plugins, exports, exports_manifest, features, idl_import_root, idl_parcelables, idl_preprocessed, idl_srcs, javacopts, licenses, manifest, neverlink, plugins, proguard_specs, resource_files, restricted_to, tags, target_compatible_with, testonly, visibility)

此规则会将其源代码编译并归档为 .jar 文件。Android 运行时库 android.jar 已隐式置于编译类路径上。

隐式输出目标

  • libname.jar:Java 归档。
  • libname-src.jar:包含来源(“来源 jar”)的归档。
  • name.aar:一个 Android 软件包,其中包含此目标的 Java 归档和资源。它不包含传递闭包。

示例

您可以在 Bazel 源代码树的 examples/android 目录中找到 Android 规则示例。

以下示例展示了如何设置 idl_import_root。让 //java/bazel/helloandroid/BUILD 包含:

android_library(
    name = "parcelable",
    srcs = ["MyParcelable.java"], # bazel.helloandroid.MyParcelable

    # MyParcelable.aidl will be used as import for other .aidl
    # files that depend on it, but will not be compiled.
    idl_parcelables = ["MyParcelable.aidl"] # bazel.helloandroid.MyParcelable

    # We don't need to specify idl_import_root since the aidl file
    # which declares bazel.helloandroid.MyParcelable
    # is present at java/bazel/helloandroid/MyParcelable.aidl
    # underneath a java root (java/).
)

android_library(
    name = "foreign_parcelable",
    srcs = ["src/android/helloandroid/OtherParcelable.java"], # android.helloandroid.OtherParcelable
    idl_parcelables = [
        "src/android/helloandroid/OtherParcelable.aidl" # android.helloandroid.OtherParcelable
    ],

    # We need to specify idl_import_root because the aidl file which
    # declares android.helloandroid.OtherParcelable is not positioned
    # at android/helloandroid/OtherParcelable.aidl under a normal java root.
    # Setting idl_import_root to "src" in //java/bazel/helloandroid
    # adds java/bazel/helloandroid/src to the list of roots
    # the aidl compiler will search for imported types.
    idl_import_root = "src",
)

# Here, OtherInterface.aidl has an "import android.helloandroid.CallbackInterface;" statement.
android_library(
    name = "foreign_interface",
    idl_srcs = [
        "src/android/helloandroid/OtherInterface.aidl" # android.helloandroid.OtherInterface
        "src/android/helloandroid/CallbackInterface.aidl" # android.helloandroid.CallbackInterface
    ],

    # As above, idl_srcs which are not correctly positioned under a java root
    # must have idl_import_root set. Otherwise, OtherInterface (or any other
    # interface in a library which depends on this one) will not be able
    # to find CallbackInterface when it is imported.
    idl_import_root = "src",
)

# MyParcelable.aidl is imported by MyInterface.aidl, so the generated
# MyInterface.java requires MyParcelable.class at compile time.
# Depending on :parcelable ensures that aidl compilation of MyInterface.aidl
# specifies the correct import roots and can access MyParcelable.aidl, and
# makes MyParcelable.class available to Java compilation of MyInterface.java
# as usual.
android_library(
    name = "idl",
    idl_srcs = ["MyInterface.aidl"],
    deps = [":parcelable"],
)

# Here, ServiceParcelable uses and thus depends on ParcelableService,
# when it's compiled, but ParcelableService also uses ServiceParcelable,
# which creates a circular dependency.
# As a result, these files must be compiled together, in the same android_library.
android_library(
    name = "circular_dependencies",
    srcs = ["ServiceParcelable.java"],
    idl_srcs = ["ParcelableService.aidl"],
    idl_parcelables = ["ServiceParcelable.aidl"],
)

参数

特性
name

Name; required

此定位条件的唯一名称。

deps

List of labels; optional

要链接的其他库的列表。 允许的库类型为:android_libraryjava_library(具有 android 限制)以及 cc_library 封装或生成 Android 目标平台的 .so 原生库。
srcs

List of labels; optional

为创建目标而处理的 .java.srcjar 文件的列表。

编译的是 .java 类型的 srcs 文件。为便于阅读,建议您不要将生成的 .java 源文件的名称放在 srcs 中。请改为将依赖的规则名称放在 srcs 中,具体如下所述。

解压缩并编译 .srcjar 类型的 srcs 文件。(如果您需要生成具有 genrule 或 build 扩展名的一组 .java 文件,这会很有用)。

如果省略 srcs,则从此规则导出 deps 中指定的任何依赖项(如需详细了解如何导出依赖项,请参阅 java_library's 导出)。不过,此行为即将被弃用,请尽量不要依赖。

assets

List of labels; optional

要打包的资源列表。 这通常是 assets 目录下所有文件的 glob。您还可以引用其他软件包中的其他规则(任何生成文件的规则)或导出的文件,只要这些文件位于相应软件包的 assets_dir 目录下。
assets_dir

String; optional

指定 assets 文件的路径。 assetsassets_dir 对用于描述打包的资源,应同时提供这两个属性,或者都不提供。
custom_package

String; optional

将为其生成 Java 源代码的 Java 软件包。默认情况下,从包含相应规则的 BUILD 文件所在的目录中推断出该软件包。您可以指定其他软件包,但强烈建议您不要这样做,因为它会导致与仅在运行时检测到的其他库有关的类路径冲突。
enable_data_binding

Boolean; optional; default is False

如果为 true,则此规则将在通过 resource_files 属性包含的布局资源中处理数据绑定表达式。如果不进行此设置,数据绑定表达式会导致构建失败。

如需构建具有数据绑定的 Android 应用,您还必须执行以下操作:

  1. 为间接依赖于此规则的所有 Android 规则设置此属性。这是因为依赖项会通过资源合并继承规则的数据绑定表达式。因此,他们还需要使用数据绑定进行构建,以解析这些表达式。
  2. 将数据绑定运行时库的 deps = 条目添加到设置此属性的所有目标。此库的位置取决于您的仓库设置。
exported_plugins

List of labels; optional

要导出到直接依赖于此库的库的 java_plugin(例如注释处理器)列表。

指定的 java_plugin 列表将应用于任何直接依赖于此库的库,就像该库已在 plugins 中明确声明这些标签一样。

exports

List of labels; optional

通过 exports 属性访问的所有规则的闭合都被视为直接依赖于具有 exports 的目标的任何规则的直接依赖项。

exports 不是其所属规则的直接依赖项。

exports_manifest

Integer; optional; default is 1

是否将清单条目导出到依赖于此目标的 android_binary 目标。uses-permissions 属性绝不会导出。
idl_import_root

String; optional

包含此库中包含的 idl 源代码的 Java 软件包树的根目录的软件包相对路径。

处理依赖于此库的 IDL 源代码时,此路径将用作导入根目录。

如果指定了 idl_import_root,则 idl_parcelablesidl_srcs 均必须位于其在 idl_import_root 下表示的对象的 Java 软件包所指定的路径。如果未指定 idl_import_rootidl_parcelablesidl_srcs 都必须位于其软件包下的 Java 根目录下所指定的路径中。

查看示例

idl_parcelables

List of labels; optional

要作为导入项提供的 Android IDL 定义列表。 对于依赖于此库的任何 android_library 目标,这些文件都将直接或通过传递传递关闭提供,但不会转换为 Java 或编译。

应仅包含与此库中的 .java 源代码直接对应的 .aidl 文件(例如 Parcelable 的自定义实现),否则应使用 idl_srcs

必须恰当地放置这些文件,以便 AI 编译器能够找到它们。如需了解其含义,请参阅 idl_import_root 说明

idl_preprocessed

List of labels; optional

要作为导入项提供的经过预处理的 Android IDL 定义的列表。 对于依赖于此库的任何 android_library 目标,这些文件都将直接或通过传递传递关闭提供,但不会转换为 Java 或编译。

应该仅包含直接与此库中的 .java 源代码对应的经过预处理的 .aidl 文件(例如,Parcelable 的自定义实现);否则,请将 idl_srcs 用于需要转换为 Java 接口的 Android IDL 定义,并将 idl_parcelable 用于非预处理 AIDL 文件。

idl_srcs

List of labels; optional

要转换为 Java 接口的 Android IDL 定义列表。 生成 Java 接口后,它们将与 srcs 的内容一起编译。

对于依赖此库的任何 android_library 目标,这些文件都将以导入形式提供,或通过直接传递方式提供。

必须恰当地放置这些文件,以便 AI 编译器能够找到它们。如需了解其含义,请参阅 idl_import_root 说明

javacopts

List of strings; optional

此目标的额外编译器选项。 遵循 Make Variable 替换和 Bourne shell 词元化要求。

这些编译器选项在全局编译器选项之后传递到 javac。

manifest

Label; optional

Android 清单文件的名称,通常为 AndroidManifest.xml。如果定义了 resource_files 或资产,则必须定义。

Boolean; optional; default is False

请仅使用此库进行编译,不要在运行时使用。标记为 neverlink 的规则的输出将不会在 .apk 的创建中使用。如果该库将在执行期间由运行时环境提供,则此属性非常有用。
plugins

List of labels; optional

要在编译时运行的 Java 编译器插件。 每当构建此目标时,都会运行插件属性中指定的每个 java_plugin。插件生成的资源会包含在目标的结果 jar 中。
proguard_specs

List of labels; optional

将用作 Proguard 规范的文件。 这些将描述 Proguard 使用的规范集。如果已指定,则会将其添加到任何 android_binary 目标中,具体取决于此库。 此处包含的文件必须具有幂等性规则,即 -dontnote、-dontwarn、<ph type="x-smartling-void-element"><br /></ph><ph type="x-smartling-placeholder">{2}</ph>、假设副作用和以 -keep 开头的规则。其他选项只能出现在 android_binary 的 proguard_specs 中,以确保非自动合并。
resource_files

List of labels; optional

要打包的资源列表。 这通常是 res 目录下所有文件的 glob
标签也可在此处引用生成的文件(通过 genrule)。唯一的限制是,生成的输出必须与包含的其他任何资源文件位于同一“res”目录下。

android_instrumentation_test

android_instrumentation_test(name, data, args, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, licenses, local, restricted_to, shard_count, size, support_apks, tags, target_compatible_with, target_device, test_app, testonly, timeout, toolchains, visibility)

android_instrumentation_test 规则用于运行 Android 插桩测试。它会启动模拟器,安装被测应用、测试应用以及任何其他所需的应用,并运行测试软件包中定义的测试。

test_app 属性指定包含测试的 android_binary。而此 android_binary 则通过其 instruments 属性指定被测 android_binary 应用。

示例

# java/com/samples/hello_world/BUILD

android_library(
    name = "hello_world_lib",
    srcs = ["Lib.java"],
    manifest = "LibraryManifest.xml",
    resource_files = glob(["res/**"]),
)

# The app under test
android_binary(
    name = "hello_world_app",
    manifest = "AndroidManifest.xml",
    deps = [":hello_world_lib"],
)
# javatests/com/samples/hello_world/BUILD

android_library(
    name = "hello_world_test_lib",
    srcs = ["Tests.java"],
    deps = [
      "//java/com/samples/hello_world:hello_world_lib",
      ...  # test dependencies such as Espresso and Mockito
    ],
)

# The test app
android_binary(
    name = "hello_world_test_app",
    instruments = "//java/com/samples/hello_world:hello_world_app",
    manifest = "AndroidManifest.xml",
    deps = [":hello_world_test_lib"],
)

android_instrumentation_test(
    name = "hello_world_uiinstrumentation_tests",
    target_device = ":some_target_device",
    test_app = ":hello_world_test_app",
)

参数

特性
name

Name; required

此定位条件的唯一名称。

support_apks

List of labels; optional

在插桩测试开始之前要在设备上安装的其他 APK。
target_device

Label; required

应在其中运行测试的 android_device

如需在已在正在运行的模拟器或实体设备上运行的模拟器中运行测试,请使用以下参数: --test_output=streamed --test_arg=--device_broker_type=LOCAL_ADB_SERVER --test_arg=--device_serial_number=$device_identifier

test_app

Label; required

包含测试类的 android_binary 目标。android_binary 目标必须通过其 instruments 属性指定它正在测试哪个目标。

android_local_test

android_local_test(name, deps, srcs, data, args, compatible_with, custom_package, densities, deprecation, enable_data_binding, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, javacopts, jvm_flags, licenses, local, manifest, manifest_values, nocompress_extensions, plugins, resource_configuration_filters, resource_jars, resource_strip_prefix, restricted_to, runtime_deps, shard_count, size, stamp, tags, target_compatible_with, test_class, testonly, timeout, toolchains, use_launcher, visibility)

此规则用于在本地(而不是在设备上)对 android_library 规则进行单元测试。它可与 Android Robolectric 测试框架搭配使用。如需详细了解如何编写 Robolectric 测试,请参阅 Android Robolectric 网站。

隐式输出目标

  • name.jar:测试的 Java 归档。
  • name-src.jar:包含来源(“来源 jar”)的归档。
  • name_deploy.jar:适合部署的 Java 部署归档(只有在明确请求时构建)。

示例

如需将 Robolectric 与 android_local_test 搭配使用,请将 Robolectric 的代码库添加到 WORKSPACE 文件中:

http_archive(
    name = "robolectric",
    urls = ["https://github.com/robolectric/robolectric/archive/<COMMIT>.tar.gz"],
    strip_prefix = "robolectric-<COMMIT>",
    sha256 = "<HASH>",
)
load("@robolectric//bazel:robolectric.bzl", "robolectric_repositories")
robolectric_repositories()
这会提取 Robolectric 所需的 maven_jar 规则。那么,每条 android_local_test 规则都应依赖于 @robolectric//bazel:robolectric。请参见下面的示例。

android_local_test(
    name = "SampleTest",
    srcs = [
        "SampleTest.java",
    ],
    manifest = "LibManifest.xml",
    deps = [
        ":sample_test_lib",
        "@robolectric//bazel:robolectric",
    ],
)

android_library(
    name = "sample_test_lib",
    srcs = [
         "Lib.java",
    ],
    resource_files = glob(["res/**"]),
    manifest = "AndroidManifest.xml",
)

参数

特性
name

Name; required

此定位条件的唯一名称。

deps

List of labels; optional

要测试的库列表以及要链接到目标的附加库。 在此属性的传递闭包中,Android 规则中声明的所有资源、资产和清单文件都可以在测试中使用。

deps 中允许的规则列表包括 android_libraryaar_importjava_importjava_libraryjava_lite_proto_library

srcs

List of labels; optional

为创建目标而处理的源文件列表。必需,除非下文所述的特殊情况。

编译的是 .java 类型的 srcs 文件。为便于阅读,建议您不要将生成的 .java 源文件的名称放在 srcs 中。请改为将依赖的规则名称放在 srcs 中,具体如下所述。

解压缩并编译 .srcjar 类型的 srcs 文件。(如果您需要生成具有 genrule 或 build 扩展名的一组 .java 文件,这会很有用)。

系统会忽略所有其他文件,前提是至少有一个上述类型的文件。否则会抛出错误。

srcs”属性是必需的属性,不能留空(除非指定了“runtime_deps”)。

custom_package

String; optional

将在其中生成 R 类的 Java 软件包。默认情况下,从包含相应规则的 BUILD 文件所在的目录中推断出软件包。使用此属性时,您可能还需要使用 test_class
densities

List of strings; optional

构建 APK 时要过滤的密度。如果相应的兼容屏幕部分尚未包含超集 StarlarkListing,则也会添加到该清单中。
enable_data_binding

Boolean; optional; default is False

如果为 true,则此规则将处理此测试所使用的已启用数据绑定的依赖项中使用的数据绑定引用。如果不进行此设置,数据绑定依赖项将不会生成必要的二进制文件级代码,并且可能会导致构建失败。
javacopts

List of strings; optional

此库的额外编译器选项。 遵循 Make Variable 替换和 Bourne shell 词元化要求。

这些编译器选项在全局编译器选项之后传递到 javac。

jvm_flags

List of strings; optional

一系列嵌入在为运行此二进制文件而生成的封装容器脚本中的标志。遵循 $(location)“使变量”替代项以及伯恩 shell 令牌化

Java 二进制文件的封装容器脚本包含 CLASSPATH 定义(以查找所有相关 JAR 文件),并调用正确的 Java 解释器。封装容器脚本生成的命令行包含主类的名称,后跟 "$@",因此您可以传递类名称之后的其他参数。但是,用于 JVM 解析的参数必须先在命令行中的类名之前指定。jvm_flags 的内容会在列出类名称之前添加到封装容器脚本中。

请注意,此属性对 *_deploy.jar 输出没有影响

manifest

Label; optional

Android 清单文件的名称,通常为 AndroidManifest.xml。如果已定义 resource_files 或资产,或被测库中的任何清单包含 minSdkVersion 标记,则必须定义此变量。
manifest_values

Dictionary: String -> String; optional

要在清单中替换的值的字典。清单中的任何 ${name} 实例都将被替换为此字典中与名称对应的值。 applicationIdversionCodeversionNameminSdkVersiontargetSdkVersionmaxSdkVersion 还将替换清单和 uses-sdk 标记的相应属性。packageName 将被忽略,并将通过 applicationId(如果已指定)或清单中的软件包进行设置。 无需为规则添加清单,即可使用 manifest_values。
nocompress_extensions

List of strings; optional

资源 APK 中未压缩的文件扩展名列表。
plugins

List of labels; optional

要在编译时运行的 Java 编译器插件。 每当构建此规则时,都会运行此属性中指定的每个 java_plugin。库也可以从使用 exported_plugins 的依赖项继承插件。该插件生成的资源将包含在此规则的 jar 文件中。
resource_configuration_filters

List of strings; optional

资源配置过滤条件列表(例如 'en'),用于将 APK 中的资源限制为 &en33;en' 配置中的资源。
resource_jars

List of labels; optional

已弃用:改用 java_import 和 deps 或 runtime_deps。
resource_strip_prefix

String; optional

要从 Java 资源中移除的路径前缀。

如果指定,则此路径前缀会从 resources 属性中的每个文件中移除。如果资源文件不在此目录中,则会出错。如果未指定(默认),则系统会根据与源文件的 Java 软件包相同的逻辑确定资源文件的路径。例如,位于 stuff/java/foo/bar/a.txt 的源文件位于 foo/bar/a.txt

runtime_deps

List of labels; optional

此类库将提供给最终二进制文件或在运行时进行测试。与普通的 deps 一样,这些修饰符会显示在运行时类路径上,但与它们不同,不会出现在编译时类路径上。此处应列出仅在运行时所需的依赖项。依赖项分析工具应忽略同时出现在 runtime_depsdeps 中的目标。
stamp

Integer; optional; default is 0

是否将 build 信息编码到二进制文件中。可能的值:
  • stamp = 1:始终在 build 二进制文件中标记 build 信息,即使在 --nostamp build 中也是如此。应避免此设置,因为这样做可能会终止二进制文件的远程缓存以及任何依赖于它的下游操作。
  • stamp = 0:始终使用常量值替换 build 信息。这样可以提供良好的构建结果缓存。
  • stamp = -1:build 信息的嵌入由 --[no]stamp 标志控制。

除非二进制文件的依赖项发生变化,否则系统不会重新构建已签名的二进制文件。

test_class

String; optional

要由测试运行程序加载的 Java 类。

此属性用于指定此测试要运行的 Java 类的名称。这种情况很少见。如果省略此参数,则将使用名称与此 android_local_test 规则的 name 对应的 Java 类。测试类需要使用 org.junit.runner.RunWith 进行注解。

use_launcher

Boolean; optional; default is True

二进制文件是否应使用自定义启动器。

如果将此属性设置为 false,对于该目标,将忽略 launcher 属性和相关的 --java_launcher 标志。

android_device

android_device(name, cache, compatible_with, default_properties, deprecation, distribs, exec_compatible_with, exec_properties, features, horizontal_resolution, licenses, platform_apks, ram, restricted_to, screen_density, system_image, tags, target_compatible_with, testonly, vertical_resolution, visibility, vm_heap)

此规则会创建使用指定规范配置的 Android 模拟器。此模拟器可以通过 bazel 运行命令或直接执行生成的脚本来启动。建议依赖于现有的 android_device 规则,而不是定义自己的规则。

此规则适用于 --run_under 标志以运行 Bazel 测试和 Blaze 运行。它会启动模拟器,将正在测试/运行的目标复制到模拟器,然后对其进行测试或运行。

如果底层 system_image 基于 X86,且最多针对 I686 CPU 架构进行了优化,则 android_device 支持创建 KVM 映像。如需使用 KVM,请将 tags = ['requires-kvm'] 添加到 android_device 规则中。

隐式输出目标

  • name_images/userdata.dat:包含用于启动模拟器的映像文件和快照
  • name_images/emulator-meta-data.pb:包含传递给模拟器以将其重启所需的序列化信息。

示例

以下示例展示了如何使用 android_device。 //java/android/helloandroid/BUILD包含

android_device(
    name = "nexus_s",
    cache = 32,
    default_properties = "nexus_s.properties",
    horizontal_resolution = 480,
    ram = 512,
    screen_density = 233,
    system_image = ":emulator_images_android_16_x86",
    vertical_resolution = 800,
    vm_heap = 32,
)

filegroup(
    name = "emulator_images_android_16_x86",
    srcs = glob(["androidsdk/system-images/android-16/**"]),
)

//java/android/helloandroid/nexus_s.properties 包含:

ro.product.brand=google
ro.product.device=crespo
ro.product.manufacturer=samsung
ro.product.model=Nexus S
ro.product.name=soju

此规则将生成图片和启动脚本。您可以通过执行 bazel run :nexus_s -- --action=start 在本地启动模拟器。该脚本会公开以下标志:

  • --adb_port:要公开 adb 的端口。如果您想要向模拟器发出 adb 命令,这是将发出 adb 连接的端口。
  • --emulator_port:用于公开模拟器的 telnet 管理控制台的端口。
  • --enable_display:如果为 true(默认为 false),则使用显示屏启动模拟器。
  • --action:启动或终止。
  • --apks_to_install:要在模拟器上安装的 apk 列表。

参数

特性
name

Name; required

此定位条件的唯一名称。

cache

Integer; required

模拟器的缓存分区的大小(以 MB 为单位)。 此值下限为 16 兆字节。
default_properties

Label; optional

要放置在模拟器上的 /default.prop 中的单个属性文件。这样一来,规则作者可以进一步将模拟器配置为更像真实设备(尤其是控制其 UserAgent 字符串和其他可能会导致应用或服务器的行为在特定设备上的行为)。此文件中的属性将替换模拟器通常设置的只读属性,例如 ro.product.model。
horizontal_resolution

Integer; required

要模拟的水平屏幕分辨率(以像素为单位)。 最小值为 240。
platform_apks

List of labels; optional

启动时要在设备上安装的 APK 列表。
ram

Integer; required

设备要模拟的 RAM 大小(以 MB 为单位)。这仅适用于整个设备,而不仅仅是设备上安装的特定应用。最小值为 64 兆字节。
screen_density

Integer; required

模拟屏幕的密度(以每英寸像素为单位)。此值下限为 30 ppi。
system_image

Label; required

一个文件组,其中包含以下文件:
  • system.img:system 分区
  • kernel-qemu:模拟器将加载的 Linux 内核
  • ramdisk.img:启动时要使用的初始映像
  • userdata.img:初始用户数据分区
  • source.properties:包含图片相关信息的属性文件
这些文件是 Android SDK 的一部分,或者由第三方提供(例如 Intel 提供 x86 映像)。
vertical_resolution

Integer; required

要模拟的垂直屏幕分辨率(以像素为单位)。 最小值为 240。
vm_heap

Integer; required

Android 将在每个进程中使用的虚拟机堆的大小(以 MB 为单位)。最小值为 16 兆字节。

android_ndk_repository

android_ndk_repository(name, api_level, path, repo_mapping)

将 Bazel 配置为使用 Android NDK,以支持使用原生代码构建 Android 目标。

请注意,Android 平台的构建还需要 WORKSPACE 文件中的 android_sdk_repository 规则。

如需了解详情,请参阅将 Android NDK 与 Bazel 搭配使用的完整文档

示例

android_ndk_repository(
    name = "androidndk",
)

上面的示例会从 $ANDROID_NDK_HOME 中找到您的 Android NDK,并检测其支持的最高 API 级别。

android_ndk_repository(
    name = "androidndk",
    path = "./android-ndk-r20",
    api_level = 24,
)

上面的示例将使用位于 ./android-ndk-r20 中的工作区内的 Android NDK。它将在编译 JNI 代码时使用 API 级别 24 的库。

CPU 功能

Android NDK 包含 cpufeatures 库,可用于在运行时检测设备的 CPU。以下示例演示了如何将 cpufeatures 与 Bazel 搭配使用。

# jni.cc
#include "ndk/sources/android/cpufeatures/cpu-features.h"
...
# BUILD
cc_library(
    name = "jni",
    srcs = ["jni.cc"],
    deps = ["@androidndk//:cpufeatures"],
)

参数

特性
name

Name; required

此定位条件的唯一名称。

api_level

Integer; optional; nonconfigurable; default is 0

作为构建基础的 Android API 级别。如果未指定,系统将使用安装的最高 API 级别。
path

String; optional; nonconfigurable

Android NDK 的绝对路径或相对路径。必须设置此属性或 $ANDROID_NDK_HOME 环境变量。

Android NDK 可以从 Android 开发者网站下载。

repo_mapping

Dictionary: String -> String; optional

从本地代码库名称到全局代码库名称的字典。这样可以控制此代码库的依赖项的工作区依赖项解析。

例如,条目 "@foo": "@bar" 声明,每当此代码库依赖于 "@foo" 时(例如对 "@foo//some:target" 的依赖项),它实际上都应在全局声明的 "@bar" ("@bar//some:target") 中解析该依赖项。

android_sdk_repository

android_sdk_repository(name, api_level, build_tools_version, path, repo_mapping)

将 Bazel 配置为使用本地 Android SDK 来支持构建 Android 目标。

示例

如需设置适用于 Bazel 的 Android SDK,最低方法是在 WORKSPACE 文件中添加一条名为“androidsdk”的 android_sdk_repository 规则,并将 $ANDROID_HOME 环境变量设置为 Android SDK 的路径。默认情况下,Bazel 将使用 Android SDK 中安装的最高 Android API 级别和构建工具版本。
android_sdk_repository(
    name = "androidsdk",
)

为了确保可重现的构建,您可以将 pathapi_levelbuild_tools_version 属性设置为特定值。如果 Android SDK 未安装指定的 API 级别或构建工具版本,构建将会失败。

android_sdk_repository(
    name = "androidsdk",
    path = "./sdk",
    api_level = 19,
    build_tools_version = "25.0.0",
)

上面的示例还演示了如何使用指向工作区的 Android SDK 相对路径。如果 Android SDK 是 Bazel 工作区的一部分(例如,如果签入到版本控制中),这将非常有用。

支持库

支持库在 Android SDK 管理器中以“Android 支持存储库”的形式提供。 这是一组带版本号的常用 Android 库,例如 Support 和 AppCompat 库,打包为本地 Maven 代码库。android_sdk_repository 会为其中每个库生成 Bazel 目标,这些目标可用于 android_binaryandroid_library 目标的依赖项中。

生成的目标的名称来自 Android 支持代码库中库的 Maven 坐标,格式为 @androidsdk//${group}:${artifact}-${version}。以下示例展示了 android_library 如何依赖于 25.0.0 版 v7 appcompat 库。

android_library(
    name = "lib",
    srcs = glob(["*.java"]),
    manifest = "AndroidManifest.xml",
    resource_files = glob(["res/**"]),
    deps = ["@androidsdk//com.android.support:appcompat-v7-25.0.0"],
)

参数

特性
name

Name; required

此定位条件的唯一名称。

api_level

Integer; optional; nonconfigurable; default is 0

作为默认构建目标的 Android API 级别。如果未指定,系统将使用安装的最高 API 级别。

用于给定 build 的 API 级别可被 android_sdk 标志替换。无论是否指定此属性,android_sdk_repository 都会为安装在 SDK 中名为 @androidsdk//:sdk-${level} 的每个 API 级别创建一个 android_sdk 目标。例如,如需针对非默认 API 级别进行构建,请使用以下代码:bazel build --android_sdk=@androidsdk//:sdk-19 //java/com/example:app

如需查看 android_sdk_repository 生成的所有 android_sdk 目标,您可以运行 bazel query "kind(android_sdk, @androidsdk//...)"

build_tools_version

String; optional; nonconfigurable

要在 Android SDK 中使用的 Android 构建工具的版本。如果未指定,将使用安装的最新构建工具版本。

Bazel 要求使用 30.0.0 或更高版本的构建工具。

path

String; optional; nonconfigurable

Android SDK 的绝对或相对路径。必须设置此属性或 $ANDROID_HOME 环境变量。

Android SDK 可以从 Android 开发者网站下载。

repo_mapping

Dictionary: String -> String; optional

从本地代码库名称到全局代码库名称的字典。这样可以控制此代码库的依赖项的工作区依赖项解析。

例如,条目 "@foo": "@bar" 声明,每当此代码库依赖于 "@foo" 时(例如对 "@foo//some:target" 的依赖项),它实际上都应在全局声明的 "@bar" ("@bar//some:target") 中解析该依赖项。