สคริปต์บิลด์ CMake เป็นไฟล์ข้อความธรรมดาที่คุณต้องตั้งชื่อว่า CMakeLists.txt และมีคำสั่งที่ CMake ใช้เพื่อสร้างไลบรารี C/C++ หากแหล่งที่มาแบบเนทีฟของคุณยังไม่มีสคริปต์บิลด์ CMake คุณต้องสร้างขึ้นเองและรวมคำสั่ง CMake ที่เหมาะสมไว้ด้วย ดูวิธีติดตั้ง CMake ได้ที่ติดตั้งและกำหนดค่า NDK และ CMake
ส่วนนี้จะครอบคลุมคำสั่งพื้นฐานบางอย่างที่คุณควรใส่ไว้ในสคริปต์บิลด์เพื่อบอก CMake ว่าจะใช้แหล่งที่มาใดเมื่อสร้างไลบรารีแบบเนทีฟ ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบอย่างเป็นทางการเกี่ยวกับคำสั่ง CMake
หลังจากกำหนดค่าสคริปต์บิลด์ CMake ใหม่แล้ว คุณต้องกำหนดค่า Gradle เพื่อรวมโปรเจ็กต์ CMake เป็นทรัพยากร Dependency ของบิลด์ เพื่อให้ Gradle สร้างและแพ็กเกจไลบรารีแบบเนทีฟด้วย APK ของแอป
หมายเหตุ: หากโปรเจ็กต์ใช้ ndk-build คุณไม่จำเป็นต้องสร้างสคริปต์บิลด์ CMake คุณสามารถกำหนดค่า Gradle ให้รวมโปรเจ็กต์ไลบรารีแบบเนทีฟที่มีอยู่ได้โดยระบุเส้นทางไปยังไฟล์ Android.mk
สร้างสคริปต์บิลด์ CMake
หากต้องการสร้างไฟล์ข้อความธรรมดาที่ใช้เป็นสคริปต์บิลด์ CMake ได้ ให้ทำดังนี้
- เปิดแผงโปรเจ็กต์จากด้านซ้ายของ IDE แล้วเลือกมุมมองโปรเจ็กต์จากเมนูแบบเลื่อนลง
- คลิกขวาที่ไดเรกทอรีรากของ your-module แล้วเลือกใหม่ > ไฟล์
หมายเหตุ: คุณสร้างสคริปต์บิลด์ในตำแหน่งใดก็ได้ที่ต้องการ อย่างไรก็ตาม เมื่อกำหนดค่าสคริปต์บิลด์ เส้นทางไปยังไฟล์ต้นฉบับและไลบรารีแบบเนทีฟจะสัมพันธ์กับตำแหน่งของสคริปต์บิลด์
- ป้อน "CMakeLists.txt" เป็นชื่อไฟล์ แล้วคลิกตกลง
ตอนนี้คุณกำหนดค่าสคริปต์บิลด์ได้โดยเพิ่มคำสั่ง CMake หากต้องการสั่งให้ CMake สร้างไลบรารีแบบเนทีฟจากซอร์สโค้ดแบบเนทีฟ ให้เพิ่มคำสั่ง cmake_minimum_required() และ add_library() ลงในสคริปต์บิลด์ ดังนี้
# Sets the minimum version of CMake required to build your native library.
# This ensures that a certain set of CMake features is available to
# your build.
cmake_minimum_required(VERSION 3.4.1)
# Specifies a library name, specifies whether the library is STATIC or
# SHARED, and provides relative paths to the source code. You can
# define multiple libraries by adding multiple add_library() commands,
# and CMake builds them for you. When you build your app, Gradle
# automatically packages shared libraries with your APK.
add_library( # Specifies the name of the library.
native-lib
# Sets the library as a shared library.
SHARED
# Provides a relative path to your source file(s).
src/main/cpp/native-lib.cpp )
เคล็ดลับ: คุณสามารถใช้คำสั่ง add_executable() เพื่อบอกให้ CMake สร้างไฟล์ปฏิบัติการจากไฟล์ต้นฉบับแทนได้ ซึ่งคล้ายกับวิธีที่คุณบอกให้ CMake สร้างไลบรารีแบบเนทีฟจากไฟล์ต้นฉบับ อย่างไรก็ตาม การสร้างไฟล์ปฏิบัติการจากแหล่งที่มาแบบเนทีฟเป็นตัวเลือก และการสร้างไลบรารีแบบเนทีฟเพื่อแพ็กเกจลงใน APK จะตอบสนองข้อกำหนดส่วนใหญ่ของโปรเจ็กต์
เมื่อคุณเพิ่มไฟล์ต้นฉบับหรือไลบรารีลงในสคริปต์บิลด์ CMake โดยใช้ add_library() Android Studio จะแสดงไฟล์ส่วนหัวที่เกี่ยวข้องในมุมมองโปรเจ็กต์ด้วยหลังจากที่คุณซิงค์โปรเจ็กต์ อย่างไรก็ตาม เพื่อให้ CMake ค้นหาไฟล์ส่วนหัวของคุณได้ในระหว่างเวลาคอมไพล์ คุณต้องเพิ่มคำสั่ง include_directories() ลงในสคริปต์บิลด์ CMake และระบุเส้นทางไปยังส่วนหัว ดังนี้
add_library(...) # Specifies a path to native header files. include_directories(src/main/cpp/include/)
รูปแบบที่ CMake ใช้ในการตั้งชื่อไฟล์ของไลบรารีมีดังนี้
liblibrary-name.so
ตัวอย่างเช่น หากคุณระบุ "native-lib" เป็นชื่อคลังที่ใช้ร่วมกันในสคริปต์บิลด์ CMake จะสร้างไฟล์ชื่อ libnative-lib.so อย่างไรก็ตาม เมื่อโหลดไลบรารีนี้ในโค้ด Java หรือ Kotlin ให้ใช้ชื่อที่คุณระบุไว้ในสคริปต์บิลด์ CMake ดังนี้
companion object { init { System.loadLibrary("native-lib") } }
หมายเหตุ: หากเปลี่ยนชื่อหรือนำไลบรารีในสคริปต์บิลด์ CMake ออก คุณต้องล้างโปรเจ็กต์ก่อนที่ Gradle จะใช้การเปลี่ยนแปลงหรือนำไลบรารีเวอร์ชันเก่าออกจาก APK หากต้องการล้างโปรเจ็กต์ ให้เลือก Build > Clean Project จากแถบเมนู
Android Studio จะเพิ่มไฟล์ต้นฉบับและส่วนหัวลงในกลุ่ม cpp ในแผงโปรเจ็กต์โดยอัตโนมัติ การใช้คำสั่ง add_library() หลายคำสั่งจะช่วยให้คุณกำหนดไลบรารีเพิ่มเติมสำหรับ CMake เพื่อสร้างจากไฟล์ต้นฉบับอื่นๆ ได้
เพิ่ม NDK API
Android NDK มีชุด API และไลบรารีแบบเนทีฟที่อาจเป็นประโยชน์สำหรับคุณ คุณใช้ API เหล่านี้ได้โดยรวมไลบรารี NDK ไว้ในไฟล์สคริปต์ CMakeLists.txt ของโปรเจ็กต์
ไลบรารี NDK ที่สร้างไว้ล่วงหน้ามีอยู่ในแพลตฟอร์ม Android อยู่แล้ว คุณจึงไม่จำเป็นต้องสร้างหรือแพ็กเกจไลบรารีเหล่านั้นลงใน APK เนื่องจากไลบรารี NDK เป็นส่วนหนึ่งของเส้นทางการค้นหาของ CMake อยู่แล้ว คุณจึงไม่จำเป็นต้องระบุตำแหน่งของไลบรารีในการติดตั้ง NDK ในเครื่อง เพียงแค่ระบุชื่อไลบรารีที่ต้องการใช้และลิงก์กับไลบรารีแบบเนทีฟของคุณเองให้กับ CMake
เพิ่มคำสั่ง find_library() ลงในสคริปต์บิลด์ CMake เพื่อค้นหาไลบรารี NDK และจัดเก็บเส้นทางเป็นตัวแปร คุณใช้ตัวแปรนี้เพื่ออ้างอิงไลบรารี NDK ในส่วนอื่นๆ ของสคริปต์บิลด์
ตัวอย่างต่อไปนี้จะค้นหาไลบรารีการสนับสนุนบันทึกเฉพาะ Android และจัดเก็บเส้นทางไว้ใน log-lib
find_library( # Defines the name of the path variable that stores the
# location of the NDK library.
log-lib
# Specifies the name of the NDK library that
# CMake needs to locate.
log )
เพื่อให้ไลบรารีแบบเนทีฟเรียกใช้ฟังก์ชันในไลบรารี log ได้ คุณต้องลิงก์ไลบรารีโดยใช้คำสั่ง target_link_libraries() ในสคริปต์บิลด์ CMake ดังนี้
find_library(...)
# Links your native library against one or more other native libraries.
target_link_libraries( # Specifies the target library.
native-lib
# Links the log library to the target library.
${log-lib} )
นอกจากนี้ NDK ยังมีไลบรารีบางรายการเป็นซอร์สโค้ดที่คุณต้องสร้างและลิงก์กับไลบรารีแบบเนทีฟด้วย คุณสามารถคอมไพล์ซอร์สโค้ดเป็นไลบรารีแบบเนทีฟได้โดยใช้คำสั่ง add_library() ในสคริปต์บิลด์ CMake หากต้องการระบุเส้นทางไปยังไลบรารี NDK ในเครื่อง คุณสามารถใช้ตัวแปรเส้นทาง ANDROID_NDK ซึ่ง Android Studio จะกำหนดให้คุณโดยอัตโนมัติ
คำสั่งต่อไปนี้จะบอกให้ CMake สร้าง android_native_app_glue.c ซึ่งจัดการเหตุการณ์ในวงจร NativeActivity และการป้อนข้อมูลด้วยการสัมผัส ให้เป็นไลบรารีแบบคงที่และลิงก์กับ native-lib
add_library( app-glue
STATIC
${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c )
# You need to link static libraries against your shared native library.
target_link_libraries( native-lib app-glue ${log-lib} )
เพิ่มไลบรารีที่สร้างไว้ล่วงหน้าอื่นๆ
การเพิ่มไลบรารีที่สร้างไว้ล่วงหน้าจะคล้ายกับการระบุไลบรารีแบบเนทีฟอื่นสำหรับ CMake เพื่อสร้าง อย่างไรก็ตาม เนื่องจากไลบรารีสร้างขึ้นแล้ว คุณจึงต้องใช้แฟล็ก IMPORTED เพื่อบอก CMake ว่าคุณต้องการนำเข้าไลบรารีไปยังโปรเจ็กต์เท่านั้น
add_library( imported-lib
SHARED
IMPORTED )
จากนั้นคุณต้องระบุเส้นทางไปยังไลบรารีโดยใช้คำสั่ง set_target_properties() ดังที่แสดงด้านล่าง
ไลบรารีบางรายการมีแพ็กเกจแยกต่างหากสำหรับสถาปัตยกรรม CPU ที่เฉพาะเจาะจง หรือ อินเทอร์เฟซแบบไบนารีของแอปพลิเคชัน (ABI) และจัดระเบียบไว้ในไดเรกทอรีแยกต่างหาก วิธีนี้ช่วยให้ไลบรารีใช้ประโยชน์จากสถาปัตยกรรม CPU บางอย่างได้ ขณะเดียวกันก็ช่วยให้คุณใช้เฉพาะเวอร์ชันของไลบรารีที่ต้องการได้ หากต้องการเพิ่มไลบรารีหลายเวอร์ชัน ABI ลงในสคริปต์บิลด์ CMake โดยไม่ต้องเขียนคำสั่งหลายรายการสำหรับไลบรารีแต่ละเวอร์ชัน คุณสามารถใช้ตัวแปรเส้นทาง ANDROID_ABI ได้ ตัวแปรนี้ใช้รายการ ABI เริ่มต้นที่ NDK รองรับ หรือรายการ ABI ที่กรองแล้วซึ่งคุณกำหนดค่า Gradle ด้วยตนเองให้ใช้ เช่น
add_library(...)
set_target_properties( # Specifies the target library.
imported-lib
# Specifies the parameter you want to define.
PROPERTIES IMPORTED_LOCATION
# Provides the path to the library you want to import.
imported-lib/src/${ANDROID_ABI}/libimported-lib.so )
เพื่อให้ CMake ค้นหาไฟล์ส่วนหัวของคุณในระหว่างเวลาคอมไพล์ คุณต้องใช้คำสั่ง include_directories() และรวมเส้นทางไปยังไฟล์ส่วนหัวของคุณด้วย:
include_directories( imported-lib/include/ )
หมายเหตุ: หากต้องการแพ็กเกจไลบรารีที่สร้างไว้ล่วงหน้าซึ่งไม่ใช่ทรัพยากร Dependency ของเวลาบิลด์ เช่น เมื่อเพิ่มไลบรารีที่สร้างไว้ล่วงหน้าซึ่งเป็นทรัพยากร Dependency ของ imported-lib คุณไม่จำเป็นต้องทำตามวิธีการต่อไปนี้เพื่อลิงก์ไลบรารี
หากต้องการลิงก์ไลบรารีที่สร้างไว้ล่วงหน้ากับไลบรารีแบบเนทีฟของคุณเอง ให้เพิ่มไลบรารีดังกล่าวลงในคำสั่ง target_link_libraries() ในสคริปต์บิลด์ CMake ดังนี้
target_link_libraries( native-lib imported-lib app-glue ${log-lib} )
หากต้องการรวมไลบรารีที่สร้างไว้ล่วงหน้าลงใน APK คุณต้องกำหนดค่า Gradle ด้วยตนเองด้วยบล็อก sourceSets เพื่อรวมเส้นทางไปยังไฟล์ .so หลังจากสร้าง APK แล้ว คุณสามารถยืนยันไลบรารีที่ Gradle แพ็กเกจลงใน APK ได้โดยใช้ตัววิเคราะห์ APK
รวมโปรเจ็กต์ CMake อื่นๆ
หากต้องการสร้างโปรเจ็กต์ CMake หลายโปรเจ็กต์และรวมเอาต์พุตไว้ในโปรเจ็กต์ Android คุณสามารถใช้ไฟล์ CMakeLists.txt ไฟล์เดียวเป็นสคริปต์บิลด์ CMake ระดับบนสุด (ซึ่งเป็นสคริปต์ที่คุณลิงก์กับ Gradle) และเพิ่มโปรเจ็กต์ CMake อื่นๆ เป็นทรัพยากร Dependency ของสคริปต์บิลด์นั้น สคริปต์บิลด์ CMake ระดับบนสุดต่อไปนี้ใช้คำสั่ง add_subdirectory() เพื่อระบุไฟล์ CMakeLists.txt อื่นเป็นทรัพยากร Dependency ของบิลด์ แล้วลิงก์กับเอาต์พุตของไฟล์นั้นเช่นเดียวกับไลบรารีที่สร้างไว้ล่วงหน้าอื่นๆ
# Sets lib_src_DIR to the path of the target CMake project.
set( lib_src_DIR ../gmath )
# Sets lib_build_DIR to the path of the desired output directory.
set( lib_build_DIR ../gmath/outputs )
file(MAKE_DIRECTORY ${lib_build_DIR})
# Adds the CMakeLists.txt file located in the specified directory
# as a build dependency.
add_subdirectory( # Specifies the directory of the CMakeLists.txt file.
${lib_src_DIR}
# Specifies the directory for the build outputs.
${lib_build_DIR} )
# Adds the output of the additional CMake build as a prebuilt static
# library and names it lib_gmath.
add_library( lib_gmath STATIC IMPORTED )
set_target_properties( lib_gmath PROPERTIES IMPORTED_LOCATION
${lib_build_DIR}/${ANDROID_ABI}/lib_gmath.a )
include_directories( ${lib_src_DIR}/include )
# Links the top-level CMake build output against lib_gmath.
target_link_libraries( native-lib ... lib_gmath )
เรียกใช้ CMake จากบรรทัดคำสั่ง
ใช้คำสั่งต่อไปนี้เพื่อเรียก CMake เพื่อสร้างโปรเจ็กต์ Ninja นอก Android Studio
cmake
-Hpath/to/cmakelists/folder
-Bpath/to/generated/ninja/project/debug/ABI
-DANDROID_ABI=ABI // For example, arm64-v8a
-DANDROID_PLATFORM=platform-version-string // For example, android-16
-DANDROID_NDK=android-sdk/ndk/ndk-version
-DCMAKE_TOOLCHAIN_FILE=android-sdk/ndk/ndk-version/build/cmake/android.toolchain.cmake
-G Ninja
คำสั่งนี้จะสร้างโปรเจ็กต์ Ninja ที่สามารถเรียกใช้เพื่อสร้างไลบรารีที่เรียกใช้ได้ของ Android (ไฟล์ .so) ต้องใช้ CMAKE_TOOLCHAIN_FILE เพื่อใช้การรองรับ CMake ของ NDK สำหรับ CMake 3.21 ขึ้นไป คุณสามารถใช้การรองรับ NDK ในตัวของ CMake แทนได้ แต่ต้องใช้กลุ่มตัวแปรที่แตกต่างกันตามที่อธิบายไว้ในเอกสารประกอบการคอมไพล์แบบข้ามระบบสำหรับ Android ของ CMake