การใช้ชุดพัฒนาซอฟต์แวร์แบบเนทีฟของ Android กับ Bazel

หากคุณเพิ่งเริ่มใช้ Bazel โปรดเริ่มต้นด้วยบทแนะนำการสร้าง Android ด้วย Bazel

ภาพรวม

Bazel สามารถทำงานในการกำหนดค่าการสร้างที่แตกต่างกันได้มากมาย รวมถึงการกำหนดค่าหลายรายการที่ใช้ชุดเครื่องมือ Android Native Development Kit (NDK) ซึ่งหมายความว่ากฎปกติ cc_libraryและcc_binaryสามารถคอมไพล์สำหรับ Android ได้โดยตรงภายใน 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

การเริ่มใช้งานอย่างง่าย

หากต้องการสร้าง C++ สำหรับ Android เพียงเพิ่มcc_libraryการอ้างอิงไปยังกฎ android_binary หรือ android_library

เช่น หากมีไฟล์ BUILD ต่อไปนี้สำหรับแอป Android

# 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 สร้างกราฟของโปรเจ็กต์ Android ด้วยทรัพยากร Dependency ของ cc_library

หากต้องการสร้างแอป ให้เรียกใช้คำสั่งต่อไปนี้

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_libraries ทั้งหมดเป็นไฟล์ออบเจ็กต์ที่ใช้ร่วมกัน (.so) ไฟล์เดียว ซึ่งกำหนดเป้าหมายสำหรับ ABI ของ armeabi-v7a โดยค่าเริ่มต้น หากต้องการเปลี่ยนหรือสร้างสำหรับ ABI หลายรายการพร้อมกัน โปรดดูส่วนการกำหนดค่า ABI เป้าหมาย

ตัวอย่างการตั้งค่า

ตัวอย่างนี้อยู่ในที่เก็บตัวอย่าง Bazel

ในไฟล์ BUILD.bazel มีการกำหนดเป้าหมาย 3 รายการด้วยกฎ android_binary android_library และ cc_library

android_binary เป้าหมายระดับบนสุดจะสร้าง APK

cc_library เป้าหมายมีไฟล์ต้นฉบับ C++ ไฟล์เดียวที่มีฟังก์ชัน JNI การใช้งาน:

#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 target ระบุแหล่งที่มาของ Java, ไฟล์ทรัพยากร และ การขึ้นต่อกันใน cc_library target ในตัวอย่างนี้ 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

STL ที่พร้อมใช้งานใน @androidndk มีดังนี้

สำหรับ r16 และต่ำกว่า STL เริ่มต้นคือ gnustl สำหรับ r17 ขึ้นไป จะเป็น libc++ เพื่อความสะดวก @androidndk//:default_crosstool เป้าหมายจะ มีชื่อแทนเป็น STL เริ่มต้นที่เกี่ยวข้อง

โปรดทราบว่าตั้งแต่ r18 เป็นต้นไป เราจะนำ STLport และ gnustl ออก ทำให้ libc++ เป็น STL เดียวใน NDK

ดูข้อมูลเพิ่มเติมเกี่ยวกับ STL เหล่านี้ได้ในเอกสารประกอบของ NDK

การกำหนดค่า ABI เป้าหมาย

หากต้องการกำหนดค่า ABI เป้าหมาย ให้ใช้แฟล็ก --fat_apk_cpu ดังนี้

bazel build //:app --fat_apk_cpu=comma-separated list of ABIs

โดยค่าเริ่มต้น Bazel จะสร้างโค้ด Android ที่มาพร้อมเครื่องสำหรับ armeabi-v7a หากต้องการสร้างสำหรับ x86 (เช่น สำหรับโปรแกรมจำลอง) ให้ส่ง --fat_apk_cpu=x86 หากต้องการสร้าง APK แบบ Fat สำหรับสถาปัตยกรรมหลายรายการ คุณสามารถระบุ CPU หลายรายการได้ดังนี้ --fat_apk_cpu=armeabi-v7a,x86

หากระบุ ABI มากกว่า 1 รายการ Bazel จะสร้าง APK ที่มีออบเจ็กต์ที่ใช้ร่วมกันสำหรับแต่ละ ABI

ABI ต่อไปนี้พร้อมใช้งาน ทั้งนี้ขึ้นอยู่กับการแก้ไข NDK และระดับ API ของ Android

ดูข้อมูลเพิ่มเติมเกี่ยวกับ ABI เหล่านี้ได้ในเอกสาร NDK

เราไม่แนะนำให้ใช้ APK แบบ Fat ที่มีหลาย ABI สำหรับบิลด์ที่เผยแพร่ เนื่องจากจะเพิ่ม ขนาดของ APK แต่ก็อาจมีประโยชน์สำหรับบิลด์ที่ใช้ในการพัฒนาและ QA

การเลือกมาตรฐาน C++

ใช้แฟล็กต่อไปนี้เพื่อสร้างตามมาตรฐาน C++

เช่น

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 กำลังเปลี่ยนไปใช้ แพลตฟอร์มและ ทูลเชน หากบิลด์ใช้แฟล็ก --platforms เพื่อเลือกสถาปัตยกรรมหรือระบบปฏิบัติการที่จะสร้าง คุณจะต้องส่งแฟล็ก --extra_toolchains ไปยัง Bazel เพื่อใช้ NDK

เช่น หากต้องการผสานรวมกับandroid_arm64_cgoเครื่องมือที่จัดทำโดย กฎ Go ให้ส่ง --extra_toolchains=@androidndk//:all นอกเหนือจาก แฟล็ก --platforms

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")

การลงทะเบียน Toolchain เหล่านี้จะบอกให้ Bazel ค้นหา Toolchain ในไฟล์ 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 ทำงานได้โดยไม่ต้องมี แฟล็กพิเศษใดๆ ยกเว้น --fat_apk_cpu และ --android_crosstool_top สำหรับ การกำหนดค่า ABI และ STL

การกำหนดค่าอัตโนมัตินี้ใช้การเปลี่ยน การกำหนดค่า Android เบื้องหลัง

กฎที่เข้ากันได้ เช่น android_binary จะเปลี่ยนการกำหนดค่าของทรัพยากร Dependency เป็นการกำหนดค่า Android โดยอัตโนมัติ ดังนั้นจะมีเพียง Subtree เฉพาะ Android ของบิลด์เท่านั้นที่ได้รับผลกระทบ ส่วนอื่นๆ ของกราฟการสร้างจะได้รับการประมวลผลโดยใช้การกำหนดค่าเป้าหมายระดับบนสุด และอาจประมวลผลเป้าหมายเดียวในการกำหนดค่าทั้ง 2 แบบได้ด้วย หากมีเส้นทางผ่านกราฟการสร้างเพื่อรองรับการดำเนินการดังกล่าว

เมื่อ Bazel อยู่ในการกำหนดค่าที่เข้ากันได้กับ Android ไม่ว่าจะระบุไว้ที่ ระดับบนสุดหรือเนื่องจากจุดเปลี่ยนระดับที่สูงกว่า จุดเปลี่ยนเพิ่มเติม ที่พบจะไม่แก้ไขการกำหนดค่าเพิ่มเติม

ตำแหน่งในตัวเพียงตำแหน่งเดียวที่ทริกเกอร์การเปลี่ยนไปใช้การกำหนดค่า Android คือแอตทริบิวต์ android_binary ของ deps

ตัวอย่างเช่น หากพยายามสร้างandroid_libraryเป้าหมายที่มีcc_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 ที่กำหนดเอง

การสร้าง cc_library สำหรับ Android โดยไม่ใช้ android_binary

หากต้องการสร้าง cc_binary หรือ cc_library แบบสแตนด์อโลนสำหรับ Android โดยไม่ใช้ 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 เองสร้างขึ้น ด้วย Toolchain ของ NDK (และสำหรับ Android) เนื่องจาก Toolchain ของโฮสต์ คัดลอกจาก Toolchain เป้าหมาย หากต้องการแก้ปัญหานี้ ให้ระบุค่าของ --host_crosstool_top เป็น @bazel_tools//tools/cpp:toolchain เพื่อ ตั้งค่า Toolchain C++ ของโฮสต์อย่างชัดเจน

วิธีนี้จะส่งผลต่อทั้งทรีการสร้าง

คุณใส่แฟล็กเหล่านี้ในbazelrcการกำหนดค่า (1 รายการต่อ ABI แต่ละรายการ) ได้ใน project/.bazelrc

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

จากนั้นหากต้องการสร้าง cc_library สำหรับ x86 เช่น ให้เรียกใช้คำสั่งต่อไปนี้

bazel build //my/cc/jni:target --config=android_x86

โดยทั่วไป ให้ใช้วิธีนี้กับเป้าหมายระดับต่ำ (เช่น cc_library) หรือเมื่อคุณทราบแน่ชัดว่ากำลังสร้างอะไรอยู่ ส่วนเป้าหมายระดับสูงที่คุณคาดว่าจะสร้างเป้าหมายจำนวนมากที่คุณควบคุมไม่ได้ ให้ใช้การเปลี่ยนการกำหนดค่าอัตโนมัติจาก android_binary