Android NDK รองรับการใช้ CMake เพื่อคอมไพล์โค้ด C และ C++ สำหรับแอปพลิเคชันของคุณ หน้านี้จะอธิบายวิธีใช้ CMake กับ NDK ผ่าน ExternalNativeBuild ของปลั๊กอิน Android Gradle หรือเมื่อเรียกใช้ CMake โดยตรง
ไฟล์ Toolchain ของ CMake
NDK รองรับ CMake ผ่านไฟล์ Toolchain ไฟล์ Toolchain คือไฟล์ CMake ที่ปรับแต่งลักษณะการทำงานของ Toolchain สำหรับการคอมไพล์แบบข้ามระบบ ไฟล์ Toolchain ที่ใช้สำหรับ NDK จะอยู่ใน NDK ที่ <NDK>/build/cmake/android.toolchain.cmake
พารามิเตอร์บิลด์ เช่น ABI, minSdkVersion ฯลฯ จะแสดงในบรรทัดคำสั่งเมื่อเรียกใช้ cmake ดูรายการอาร์กิวเมนต์ที่รองรับได้ที่ส่วนอาร์กิวเมนต์ Toolchain
ไฟล์ Toolchain "ใหม่"
NDK เวอร์ชันก่อนหน้าได้ทดลองใช้การติดตั้งใช้งานไฟล์ Toolchain ใหม่ซึ่งจะลดความแตกต่างของลักษณะการทำงานระหว่างการใช้ไฟล์ Toolchain ของ NDK กับการใช้การรองรับ CMake ในตัว ซึ่งทำให้ต้องทำงานจำนวนมาก (ซึ่งยังไม่เสร็จสมบูรณ์) แต่ไม่ได้ปรับปรุงลักษณะการทำงานจริงๆ เราจึงไม่ดำเนินการต่อ
ไฟล์ Toolchain "ใหม่" มีลักษณะการทำงานที่ถดถอยเมื่อเทียบกับไฟล์ Toolchain "เดิม" ลักษณะการทำงานเริ่มต้นคือเวิร์กโฟลว์ที่แนะนำ หากคุณใช้ -DANDROID_USE_LEGACY_TOOLCHAIN_FILE=OFF เราขอแนะนำให้นำแฟล็กนั้นออกจากบิลด์ ไฟล์ Toolchain ใหม่ไม่เคยมีความเท่าเทียมกับไฟล์ Toolchain เดิม จึงอาจมีการถดถอยของลักษณะการทำงาน
แม้ว่าเราจะไม่แนะนำให้ใช้ไฟล์ Toolchain ใหม่ แต่ปัจจุบันยังไม่มีแผนที่จะนำไฟล์ดังกล่าวออกจาก NDK การทำเช่นนี้จะทำให้บิลด์ที่อาศัยความแตกต่างของลักษณะการทำงานระหว่างไฟล์ Toolchain ใหม่และเดิมใช้งานไม่ได้ และน่าเสียดายที่การเปลี่ยนชื่อตัวเลือกเพื่อให้ชัดเจนว่า "เดิม" เป็นตัวเลือกที่แนะนำจริงๆ ก็จะทำให้ผู้ใช้ตัวเลือกดังกล่าวใช้งานไม่ได้เช่นกัน หากคุณพอใจกับการใช้ไฟล์ Toolchain ใหม่ คุณไม่จำเป็นต้องย้ายข้อมูล แต่โปรดทราบว่าข้อบกพร่องที่ยื่นเกี่ยวกับลักษณะการทำงานของไฟล์ Toolchain ใหม่จะไม่ได้รับการแก้ไข และคุณจะต้องย้ายข้อมูลแทน
การใช้งาน
Gradle
ระบบจะใช้ไฟล์ Toolchain ของ CMake โดยอัตโนมัติเมื่อใช้ externalNativeBuild ดูข้อมูลเพิ่มเติมได้ที่คู่มือเพิ่มโค้ด C และ C++ ลงในโปรเจ็กต์ของ Android Studio
บรรทัดคำสั่ง
เมื่อสร้างด้วย CMake นอก Gradle คุณต้องส่งไฟล์ Toolchain และอาร์กิวเมนต์ของไฟล์ไปยัง CMake เช่น
$ cmake \
-DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \
-DANDROID_ABI=$ABI \
-DANDROID_PLATFORM=android-$MINSDKVERSION \
$OTHER_ARGS
อาร์กิวเมนต์ Toolchain
คุณสามารถส่งอาร์กิวเมนต์ต่อไปนี้ไปยังไฟล์ Toolchain ของ CMake ได้ หากสร้างด้วย Gradle ให้เพิ่มอาร์กิวเมนต์ลงใน android.defaultConfig.externalNativeBuild.cmake.arguments ตามที่อธิบายไว้ในเอกสาร ExternalNativeBuild หากสร้างจากบรรทัดคำสั่ง ให้ส่งอาร์กิวเมนต์ไปยัง CMake ด้วย -D ตัวอย่างเช่น หากต้องการบังคับให้ armeabi-v7a ไม่สร้างด้วยการรองรับ Neon ให้ส่ง -DANDROID_ARM_NEON=FALSE
ANDROID_ABI
ABI เป้าหมาย ดูข้อมูลเกี่ยวกับ ABI ที่รองรับได้ที่ ABI ของ Android
Gradle
Gradle จะระบุอาร์กิวเมนต์นี้โดยอัตโนมัติ อย่าตั้งค่าอาร์กิวเมนต์นี้อย่างชัดแจ้งในไฟล์ build.gradle หากต้องการควบคุม ABI ที่ Gradle กำหนดเป้าหมาย ให้ใช้ abiFilters ตามที่อธิบายไว้ใน ABI ของ Android
บรรทัดคำสั่ง
CMake จะสร้างเป้าหมายเดียวต่อบิลด์ หากต้องการกำหนดเป้าหมาย Android ABI มากกว่า 1 รายการ คุณต้องสร้าง 1 ครั้งต่อ ABI ขอแนะนำให้ใช้ไดเรกทอรีบิลด์ที่แตกต่างกันสำหรับ ABI แต่ละรายการเพื่อหลีกเลี่ยงการชนกันระหว่างบิลด์
| ค่า | หมายเหตุ |
|---|---|
armeabi-v7a |
|
armeabi-v7a with NEON |
เหมือนกับ armeabi-v7a |
arm64-v8a |
|
x86 |
|
x86_64 |
ANDROID_ARM_MODE
ระบุว่าจะสร้างคำสั่ง ARM หรือ Thumb สำหรับ armeabi-v7a หรือไม่ ไม่มีผลกับ ABI อื่นๆ ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบเกี่ยวกับ Android ABI
| ค่า | หมายเหตุ |
|---|---|
| arm | |
| นิ้วหัวแม่มือ | ลักษณะการทำงานเริ่มต้น |
ANDROID_NATIVE_API_LEVEL
ชื่อแทนสำหรับ ANDROID_PLATFORM
ANDROID_PLATFORM
ระบุระดับ API ขั้นต่ำที่แอปพลิเคชันหรือไลบรารีรองรับ ค่านี้สอดคล้องกับ minSdkVersion ของแอปพลิเคชัน
Gradle
เมื่อใช้ปลั๊กอิน Android Gradle ระบบจะตั้งค่านี้ให้ตรงกับ minSdkVersion ของแอปพลิเคชันโดยอัตโนมัติ และไม่ควรตั้งค่าด้วยตนเอง
บรรทัดคำสั่ง
เมื่อเรียกใช้ CMake โดยตรง ค่านี้จะใช้ค่าเริ่มต้นเป็นระดับ API ต่ำสุดที่ NDK ที่ใช้อยู่รองรับ ตัวอย่างเช่น สำหรับ NDK r20 ค่านี้จะใช้ค่าเริ่มต้นเป็นระดับ API 16
ระบบรองรับพารามิเตอร์นี้หลายรูปแบบ ดังนี้
android-$API_LEVEL$API_LEVELandroid-$API_LETTER
รูปแบบ $API_LETTER ช่วยให้คุณระบุ android-N ได้โดยไม่ต้องกำหนดหมายเลขที่เชื่อมโยงกับรุ่นนั้น โปรดทราบว่าบางรุ่นได้รับการเพิ่ม API โดยไม่มีการเพิ่มตัวอักษร คุณระบุ API เหล่านี้ได้โดยต่อท้ายด้วย -MR1 เช่น ระดับ API 25 คือ android-N-MR1
ANDROID_STL
ระบุ STL ที่จะใช้สำหรับแอปพลิเคชันนี้ ดูข้อมูลเพิ่มเติมได้ที่การรองรับไลบรารี C++ โดยค่าเริ่มต้น ระบบจะใช้ c++_static
| ค่า | หมายเหตุ |
|---|---|
| c++_shared | ตัวแปรไลบรารีที่ใช้ร่วมกันของ libc++ |
| c++_static | ตัวแปรไลบรารีแบบคงที่ของ libc++ |
| ไม่มี | ไม่รองรับไลบรารีมาตรฐาน C++ |
| ระบบ | STL ของระบบ |
จัดการแฟล็กคอมไพเลอร์
หากต้องการส่งแฟล็กที่เฉพาะเจาะจงไปยังคอมไพเลอร์หรือ Linker สำหรับบิลด์ โปรดดูเอกสารประกอบของ CMake สำหรับ set_target_compile_options และกลุ่มตัวเลือกที่เกี่ยวข้อง ส่วน "ดูเพิ่มเติม" ที่ด้านล่างของหน้านั้นมีเบาะแสที่เป็นประโยชน์อยู่
โดยทั่วไป แนวทางปฏิบัติแนะนำคือการใช้แฟล็กคอมไพเลอร์เป็นขอบเขตที่แคบที่สุดที่มีอยู่ แฟล็กที่คุณต้องการใช้กับเป้าหมายทั้งหมด (เช่น -Werror) ไม่สะดวกที่จะทำซ้ำต่อโมดูล แต่ก็ยังไม่ควรใช้ทั่วโลก (CMAKE_CXX_FLAGS) เนื่องจากอาจส่งผลที่ไม่พึงประสงค์ต่อทรัพยากร Dependency ของบุคคลที่สามในโปรเจ็กต์ ในกรณีเช่นนี้ คุณสามารถใช้แฟล็กที่ขอบเขตไดเรกทอรี (add_compile_options) ได้
สำหรับแฟล็กคอมไพเลอร์ชุดย่อยที่แคบ คุณยังตั้งค่าแฟล็กเหล่านั้นในไฟล์ build.gradle โดยใช้ cppFlags หรือพร็อพเพอร์ตี้ที่คล้ายกันได้ด้วย คุณไม่ควรทำเช่นนี้ แฟล็กที่ส่งไปยัง CMake จาก Gradle จะมีลักษณะการทำงานตามลำดับความสำคัญที่น่าประหลาดใจ โดยในบางกรณีจะลบล้างแฟล็กที่ส่งโดยนัยโดยการติดตั้งใช้งานซึ่งจำเป็นสำหรับการสร้างโค้ด Android เราขอแนะนำให้จัดการลักษณะการทำงานของ CMake ใน CMake โดยตรงเสมอ หากต้องการควบคุมแฟล็กคอมไพเลอร์ต่อ AGP buildType โปรดดูหัวข้อทำงานกับประเภทบิลด์ AGP ใน CMake
ทำงานกับประเภทบิลด์ AGP ใน CMake
หากต้องการปรับแต่งลักษณะการทำงานของ CMake ให้เหมาะกับ buildType ของ Gradle ที่กำหนดเอง ให้ใช้บิลด์ประเภทนั้นเพื่อส่ง Flag ของ CMake เพิ่มเติม (ไม่ใช่ Flag ของคอมไพเลอร์) ที่สคริปต์บิลด์ของ CMake อ่านได้ ตัวอย่างเช่น หากคุณมีตัวแปรบิลด์ "ฟรี" และ "พรีเมียม" ที่ควบคุมโดย build.gradle.kts และคุณต้องส่งข้อมูลนั้นไปยัง CMake ให้ทำดังนี้
android {
buildTypes {
free {
externalNativeBuild {
cmake {
arguments.add("-DPRODUCT_VARIANT_PREMIUM=OFF")
}
}
}
premium {
externalNativeBuild {
cmake {
arguments.add("-DPRODUCT_VARIANT_PREMIUM=ON")
}
}
}
}
}
จากนั้นใน CMakeLists.txt ให้ทำดังนี้
if (DPRODUCT_VARIANT_PREMIUM)
# Do stuff for the premium build.
else()
# Do stuff for the free build.
endif()
คุณตั้งชื่อตัวแปรได้ตามต้องการ แต่โปรดหลีกเลี่ยงชื่อที่มีคำนำหน้า ANDROID_, APP_ หรือ CMAKE_ เพื่อไม่ให้เกิดการทับซ้อนหรือสับสนกับแฟล็กที่มีอยู่
ดูตัวอย่างได้ที่ตัวอย่าง NDK ของ Sanitizer
ทำความเข้าใจคำสั่งบิลด์ CMake
เมื่อแก้ไขข้อบกพร่องเกี่ยวกับปัญหาการสร้าง CMake คุณควรทราบอาร์กิวเมนต์การสร้างที่เฉพาะเจาะจงซึ่ง Gradle ใช้เมื่อคอมไพล์แบบข้ามระบบสำหรับ Android
ปลั๊กอิน Android Gradle จะบันทึกอาร์กิวเมนต์บิลด์ที่ใช้ในการเรียกใช้บิลด์ CMake สำหรับ ABI และคู่ประเภทบิลด์แต่ละคู่ไว้ใน build_command.txt ไฟล์เหล่านี้จะอยู่ในไดเรกทอรีต่อไปนี้
<project-root>/<module-root>/.cxx/cmake/<build-type>/<ABI>/
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างอาร์กิวเมนต์ CMake เพื่อสร้างรุ่นที่แก้ไขข้อบกพร่องได้ของตัวอย่าง hello-jni ที่กำหนดเป้าหมายสถาปัตยกรรม armeabi-v7a
Executable : ${HOME}/Android/Sdk/cmake/3.10.2.4988404/bin/cmake
arguments :
-H${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/src/main/cpp
-DCMAKE_FIND_ROOT_PATH=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/.cxx/cmake/universalDebug/prefab/armeabi-v7a/prefab
-DCMAKE_BUILD_TYPE=Debug
-DCMAKE_TOOLCHAIN_FILE=${HOME}/Android/Sdk/ndk/22.1.7171670/build/cmake/android.toolchain.cmake
-DANDROID_ABI=armeabi-v7a
-DANDROID_NDK=${HOME}/Android/Sdk/ndk/22.1.7171670
-DANDROID_PLATFORM=android-23
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a
-DCMAKE_ANDROID_NDK=${HOME}/Android/Sdk/ndk/22.1.7171670
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/build/intermediates/cmake/universalDebug/obj/armeabi-v7a
-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/build/intermediates/cmake/universalDebug/obj/armeabi-v7a
-DCMAKE_MAKE_PROGRAM=${HOME}/Android/Sdk/cmake/3.10.2.4988404/bin/ninja
-DCMAKE_SYSTEM_NAME=Android
-DCMAKE_SYSTEM_VERSION=23
-B${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/.cxx/cmake/universalDebug/armeabi-v7a
-GNinja
jvmArgs :
Build command args: []
Version: 1
ใช้ไลบรารีที่สร้างไว้ล่วงหน้า
หากไลบรารีที่สร้างไว้ล่วงหน้าที่คุณต้องการนำเข้ามีการเผยแพร่เป็น AAR ให้ทำตามเอกสารประกอบเกี่ยวกับทรัพยากร Dependency ของ Studio เพื่อนำเข้าและใช้ไลบรารีเหล่านั้น หากไม่ได้ใช้ AGP คุณสามารถทำตาม https://google.github.io/prefab/example-workflow.html แต่การย้ายข้อมูลไปยัง AGP น่าจะง่ายกว่ามาก
สำหรับไลบรารีที่ไม่ได้เผยแพร่เป็น AAR โปรดดูวิธีการใช้ไลบรารีที่สร้างไว้ล่วงหน้ากับ CMake ในเอกสารประกอบของ add_library เกี่ยวกับเป้าหมาย IMPORTED ในคู่มือ CMake
การสร้างโค้ดของบุคคลที่สาม
มีวิธีมากมายในการสร้างโค้ดของบุคคลที่สามเป็นส่วนหนึ่งของโปรเจ็กต์ CMake และตัวเลือกที่เหมาะสมที่สุดจะขึ้นอยู่กับสถานการณ์ของคุณ ตัวเลือกที่ดีที่สุดมักจะเป็นการไม่ทำเช่นนี้เลย แต่ให้สร้าง AAR สำหรับไลบรารีและใช้ในแอปพลิเคชันแทน คุณไม่จำเป็นต้องเผยแพร่ AAR นั้น ซึ่งอาจอยู่ภายในโปรเจ็กต์ Gradle
หากทำไม่ได้ ให้ทำดังนี้
- ผู้ให้บริการ (เช่น คัดลอก) แหล่งที่มาของบุคคลที่สามลงในที่เก็บของคุณและใช้ add_subdirectory เพื่อสร้าง ซึ่งจะใช้ได้ก็ต่อเมื่อไลบรารีอื่นสร้างด้วย CMake เช่นกัน
- กำหนด ExternalProject
- สร้างไลบรารีแยกต่างหากจากโปรเจ็กต์และทำตามใช้ไลบรารีที่สร้างไว้ล่วงหน้าเพื่อนำเข้าเป็นไลบรารีที่สร้างไว้ล่วงหน้า
การรองรับ YASM ใน CMake
NDK รองรับ CMake สำหรับการสร้างโค้ดแอสเซมบลีที่เขียนใน YASM เพื่อให้ทำงานบนสถาปัตยกรรม x86 และ x86-64 YASM เป็นแอสเซมเบลอร์โอเพนซอร์สสำหรับสถาปัตยกรรม x86 และ x86-64 ซึ่งอิงตามแอสเซมเบลอร์ NASM
หากต้องการสร้างโค้ดแอสเซมบลีด้วย CMake ให้ทำการเปลี่ยนแปลงต่อไปนี้ใน CMakeLists.txt ของโปรเจ็กต์
- เรียกใช้
enable_languageโดยตั้งค่าเป็นASM_NASM - เรียกใช้
add_libraryหรือadd_executableโดยขึ้นอยู่กับว่าคุณกำลังสร้างคลังที่ใช้ร่วมกันหรือไบนารีที่ปฏิบัติการได้ ในอาร์กิวเมนต์ ให้ส่งรายการไฟล์ต้นฉบับที่ประกอบด้วยไฟล์.asmสำหรับโปรแกรมแอสเซมบลีใน YASM และไฟล์.cสำหรับไลบรารีหรือฟังก์ชัน C ที่เกี่ยวข้อง
ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่คุณอาจกำหนดค่า CMakeLists.txt เพื่อสร้างโปรแกรม YASM เป็นคลังที่ใช้ร่วมกัน
cmake_minimum_required(VERSION 3.6.0)
enable_language(ASM_NASM)
add_library(test-yasm SHARED jni/test-yasm.c jni/print_hello.asm)
ดูตัวอย่างวิธีสร้างโปรแกรม YASM เป็นไฟล์ปฏิบัติการได้ที่การทดสอบ yasm ในที่เก็บ Git ของ NDK
รายงานปัญหา
หากพบปัญหาเกี่ยวกับ NDK หรือไฟล์ Toolchain ของ CMake โปรดรายงานปัญหาผ่าน Issue Tracker android-ndk/ndk ใน GitHub สำหรับปัญหาเกี่ยวกับ Gradle หรือปลั๊กอิน Android Gradle โปรดรายงานข้อบกพร่องของ Studio แทน