如果您刚开始接触 Bazel,请先学习使用 Bazel 教程。
概览
Bazel 可以在许多不同的构建配置中运行,包括使用
Android 原生开发套件 (NDK) 工具链。这意味着
您可以直接在 Android 中编译 cc_library
和 cc_binary
规则
Bazel。Bazel 使用 android_ndk_repository
仓库规则来实现此目的。
前提条件
请确保您已安装 Android SDK 和 NDK。
如需设置 SDK 和 NDK,请将以下代码段添加到 WORKSPACE
中:
android_sdk_repository(
name = "androidsdk", # Required. Name *must* be "androidsdk".
path = "/path/to/sdk", # Optional. Can be omitted if `ANDROID_HOME` environment variable is set.
)
android_ndk_repository(
name = "androidndk", # Required. Name *must* be "androidndk".
path = "/path/to/ndk", # Optional. Can be omitted if `ANDROID_NDK_HOME` environment variable is set.
)
如需详细了解 android_ndk_repository
规则,请参阅 build 百科全书条目。
如果您使用的是最新版本的 Android NDK(r22 及更高版本),请使用
android_ndk_repository
的 Starlark 实现。
请按照
自述文件。
快速入门
如需构建适用于 Android 的 C++ 代码,只需将 cc_library
依赖项添加到 android_binary
或 android_library
规则即可。
例如,假设某个 Android 应用具有以下 BUILD
文件:
# In <project>/app/src/main/BUILD.bazel
cc_library(
name = "jni_lib",
srcs = ["cpp/native-lib.cpp"],
)
android_library(
name = "lib",
srcs = ["java/com/example/android/bazel/MainActivity.java"],
resource_files = glob(["res/**/*"]),
custom_package = "com.example.android.bazel",
manifest = "LibraryManifest.xml",
deps = [":jni_lib"],
)
android_binary(
name = "app",
deps = [":lib"],
manifest = "AndroidManifest.xml",
)
此 BUILD
文件会生成以下目标图表:
图 1. 包含 cc_library 依赖项的 Android 项目的 build 图。
如需构建应用,只需运行以下命令:
bazel build //app/src/main:app
bazel build
命令会编译 Java 文件、Android 资源文件以及
cc_library
规则,并将所有内容打包到 APK 中:
$ zipinfo -1 bazel-bin/app/src/main/app.apk
nativedeps
lib/armeabi-v7a/libapp.so
classes.dex
AndroidManifest.xml
...
res/...
...
META-INF/CERT.SF
META-INF/CERT.RSA
META-INF/MANIFEST.MF
Bazel 会将所有 cc_library 编译到单个共享对象 (.so
) 文件中,默认以 armeabi-v7a
ABI 为目标平台。如需更改此设置或同时针对多个 ABI 进行构建,请参阅配置目标 ABI 部分。
示例设置
在 BUILD.bazel
文件中,使用 android_binary
定义了三个目标,
android_library
和 cc_library
规则。
android_binary
顶级目标会构建 APK。
cc_library
目标包含具有 JNI 函数的单个 C++ 源文件
实现:
#include <jni.h>
#include <string>
extern "C"
JNIEXPORT jstring
JNICALL
Java_com_example_android_bazel_MainActivity_stringFromJNI(
JNIEnv *env,
jobject /* this */) {
std::string hello = "Hello from C++";
return env->NewStringUTF(hello.c_str());
}
android_library
目标用于指定 Java 源文件、资源文件以及
依赖于 cc_library
目标。在此示例中,MainActivity.java
会加载
共享对象文件 libapp.so
,并定义了 JNI 的方法签名
函数:
public class MainActivity extends AppCompatActivity {
static {
System.loadLibrary("app");
}
@Override
protected void onCreate(Bundle savedInstanceState) {
// ...
}
public native String stringFromJNI();
}
配置 STL
如需配置 C++ STL,请使用标志 --android_crosstool_top
。
bazel build //:app --android_crosstool_top=target label
@androidndk
中的可用 STL 如下:
STL | 目标标签 |
---|---|
STLport | @androidndk//:toolchain-stlport |
libc++ | @androidndk//:toolchain-libcpp |
gnustl | @androidndk//:toolchain-gnu-libstdcpp |
对于 r16 及更低版本,默认 STL 为 gnustl
。对于 r17 及更高版本,它为 libc++
。为方便起见,目标 @androidndk//:default_crosstool
为
别名为各自的默认 STL。
请注意,从 r18 开始,STLport 和 gnustl 将被移除,这使得 libc++
成为 NDK 中唯一的 STL。
如需详细了解这些 STL,请参阅 NDK 文档。
配置目标 ABI
如需配置目标 ABI,请使用 --fat_apk_cpu
标志,如下所示:
bazel build //:app --fat_apk_cpu=comma-separated list of ABIs
默认情况下,Bazel 会为 armeabi-v7a
构建原生 Android 代码。如需针对 x86 进行构建(例如针对模拟器),请传递 --fat_apk_cpu=x86
。为多个 APK 创建一个胖 APK
则可以指定多个 CPU:--fat_apk_cpu=armeabi-v7a,x86
。
如果指定了多个 ABI,Bazel 将构建一个 APK,其中包含共享的 对象。
根据 NDK 修订版本和 Android API 级别,以下 ABI 可 可用:
NDK 修订版 | ABI |
---|---|
16 及更低 | armeabi、armeabi-v7a、arm64-v8a、mips、mips64、x86、x86_64 |
17 周岁及以上 | armeabi-v7a、arm64-v8a、x86、x86_64 |
请参阅 NDK 文档 详细了解这些 ABI。
不建议将多 ABI 胖 APK 用于发布 build,因为它们会增加 APK 的大小,但对于开发 build 和质量检查 build 而言,它们可能很有用。
选择 C++ 标准
使用以下标志根据 C++ 标准进行构建:
C++ 标准 | 标志 |
---|---|
C++98 | 默认,无需任何标志 |
C++11 | --cxxopt=-std=c++11 |
C++14 | --cxxopt=-std=c++14 |
例如:
bazel build //:app --cxxopt=-std=c++11
如需详细了解如何使用 --cxxopt
、--copt
和 --linkopt
传递编译器和链接器标志,请参阅用户手册。
编译器标记和链接器标记也可以指定为 cc_library
中的属性
使用 copts
和 linkopts
。例如:
cc_library(
name = "jni_lib",
srcs = ["cpp/native-lib.cpp"],
copts = ["-std=c++11"],
linkopts = ["-ldl"], # link against libdl
)
与平台和工具链集成
Bazel 的配置模型正朝着
平台和
工具链。如果您的
build 使用 --platforms
标志来选择架构或操作系统
您需要将 --extra_toolchains
标志传递给 Bazel
才能使用 NDK。
例如,如需与 Go 规则提供的 android_arm64_cgo
工具链集成,请除了 --platforms
标志之外,还传递 --extra_toolchains=@androidndk//:all
。
bazel build //my/cc:lib \
--platforms=@io_bazel_rules_go//go/toolchain:android_arm64_cgo \
--extra_toolchains=@androidndk//:all
您也可以直接在 WORKSPACE
文件中注册它们:
android_ndk_repository(name = "androidndk")
register_toolchains("@androidndk//:all")
注册这些工具链会告知 Bazel 在解析架构和操作系统约束条件时在 NDK BUILD
文件(适用于 NDK 20)中查找它们:
toolchain(
name = "x86-clang8.0.7-libcpp_toolchain",
toolchain_type = "@bazel_tools//tools/cpp:toolchain_type",
target_compatible_with = [
"@platforms//os:android",
"@platforms//cpu:x86_32",
],
toolchain = "@androidndk//:x86-clang8.0.7-libcpp",
)
toolchain(
name = "x86_64-clang8.0.7-libcpp_toolchain",
toolchain_type = "@bazel_tools//tools/cpp:toolchain_type",
target_compatible_with = [
"@platforms//os:android",
"@platforms//cpu:x86_64",
],
toolchain = "@androidndk//:x86_64-clang8.0.7-libcpp",
)
toolchain(
name = "arm-linux-androideabi-clang8.0.7-v7a-libcpp_toolchain",
toolchain_type = "@bazel_tools//tools/cpp:toolchain_type",
target_compatible_with = [
"@platforms//os:android",
"@platforms//cpu:arm",
],
toolchain = "@androidndk//:arm-linux-androideabi-clang8.0.7-v7a-libcpp",
)
toolchain(
name = "aarch64-linux-android-clang8.0.7-libcpp_toolchain",
toolchain_type = "@bazel_tools//tools/cpp:toolchain_type",
target_compatible_with = [
"@platforms//os:android",
"@platforms//cpu:aarch64",
],
toolchain = "@androidndk//:aarch64-linux-android-clang8.0.7-libcpp",
)
工作原理:引入 Android 配置转换
android_binary
规则可以明确要求 Bazel 在与 Android 兼容的配置中构建其依赖项,以便 Bazel build 正常运行,而无需任何特殊标志(适用于 ABI 和 STL 配置的 --fat_apk_cpu
和 --android_crosstool_top
除外)。
在后台,这种自动配置使用 Android 配置 过渡效果。
兼容的规则(如 android_binary
)会自动更改
将其依赖项配置为 Android 配置,因此
build 的 Android 专用子树会受到影响。构建的其他部分
均使用顶级目标配置进行处理。它甚至可能
在两种配置中都处理同一个目标(如果
来支持这一点
一旦 Bazel 处于 Android 兼容的配置(在顶层指定或因更高级别的转换点而处于该配置),遇到的其他转换点便不会进一步修改配置。
唯一会触发向 Android 转换的内置位置
是 android_binary
的 deps
属性。
例如,如果您尝试使用 cc_library
构建 android_library
目标,
依赖项,则可能会遇到有关缺少 JNI 的错误
标头:
ERROR: project/app/src/main/BUILD.bazel:16:1: C++ compilation of rule '//app/src/main:jni_lib' failed (Exit 1)
app/src/main/cpp/native-lib.cpp:1:10: fatal error: 'jni.h' file not found
#include <jni.h>
^~~~~~~
1 error generated.
Target //app/src/main:lib failed to build
Use --verbose_failures to see the command lines of failed build steps.
理想情况下,这些自动转换应该能够让 Bazel 在
大多数情况下都是这样。不过,如果 Bazel 命令行上的目标已经位于任何这些转换规则之下(例如,C++ 开发者在测试特定 cc_library
),则必须使用自定义 --crosstool_top
。
在不使用 android_binary
的情况下构建适用于 Android 的 cc_library
如需针对 Android 构建独立的 cc_binary
或 cc_library
,而不使用
android_binary
,请使用 --crosstool_top
、--cpu
和 --host_crosstool_top
标志。
例如:
bazel build //my/cc/jni:target \
--crosstool_top=@androidndk//:default_crosstool \
--cpu=<abi> \
--host_crosstool_top=@bazel_tools//tools/cpp:toolchain
在此示例中,我们构建了顶级 cc_library
和 cc_binary
目标
使用 NDK 工具链。不过,这会导致 Bazel 自己的主机工具使用 NDK 工具链(因此适用于 Android)进行构建,因为主机工具链是从目标工具链复制的。要解决此问题,请指定
--host_crosstool_top
将变为@bazel_tools//tools/cpp:toolchain
至
明确设置主机的 C++ 工具链。
使用此方法,整个 build 树都会受到影响。
这些标志可放入 project/.bazelrc
中的 bazelrc
配置(每个 ABI 一个)中:
common:android_x86 --crosstool_top=@androidndk//:default_crosstool
common:android_x86 --cpu=x86
common:android_x86 --host_crosstool_top=@bazel_tools//tools/cpp:toolchain
common:android_armeabi-v7a --crosstool_top=@androidndk//:default_crosstool
common:android_armeabi-v7a --cpu=armeabi-v7a
common:android_armeabi-v7a --host_crosstool_top=@bazel_tools//tools/cpp:toolchain
# In general
common:android_<abi> --crosstool_top=@androidndk//:default_crosstool
common:android_<abi> --cpu=<abi>
common:android_<abi> --host_crosstool_top=@bazel_tools//tools/cpp:toolchain
然后,如需为 x86
构建 cc_library
,请运行以下命令:
bazel build //my/cc/jni:target --config=android_x86
通常,对于低级目标(例如 cc_library
)或您确切知道要构建的内容时,请使用此方法;对于您预计要构建许多不受控制的目标的高级目标,请依赖 android_binary
中的自动配置转换。