CMake

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_LEVEL
  • android-$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 ของโปรเจ็กต์

  1. เรียกใช้ enable_language โดยตั้งค่าเป็น ASM_NASM
  2. เรียกใช้ 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 แทน