สคริปต์บิลด์ 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 และ
เลือก New > ไฟล์
หมายเหตุ: คุณสร้างสคริปต์บิลด์ในตำแหน่งใดก็ได้ที่ต้องการ อย่างไรก็ตาม เมื่อกำหนดค่าสคริปต์บิลด์ เส้นทางไปยังแหล่งที่มาดั้งเดิม ไฟล์และไลบรารีสัมพันธ์กับตำแหน่งของสคริปต์บิลด์
- ป้อน "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 )
เคล็ดลับ: คล้ายกับที่คุณบอกให้ CMake สร้างไลบรารีเนทีฟจาก
คุณสามารถใช้
add_executable() เพื่อบอก 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 ดังนี้
Kotlin
companion object { init { System.loadLibrary("native-lib"); } }
Java
static { System.loadLibrary("native-lib"); }
หมายเหตุ: หากคุณเปลี่ยนชื่อหรือนำไลบรารีใน CMake ออก คุณต้องล้างโปรเจ็กต์ก่อนที่ Gradle จะใช้การเปลี่ยนแปลงหรือ นำไลบรารีเวอร์ชันเก่าออกจาก APK ของคุณ วิธีทำความสะอาด โปรเจ็กต์ เลือก สร้าง > ล้างโปรเจ็กต์จากแถบเมนู
Android Studio จะเพิ่มไฟล์ต้นฉบับและส่วนหัวลงในไฟล์
กลุ่ม cpp ในแผงโปรเจ็กต์ โดยการใช้
คำสั่ง add_library() หลายรายการ คุณสามารถกำหนดคำสั่งเพิ่มเติม
ไลบรารีสำหรับ CMake เพื่อสร้างจากไฟล์ต้นฉบับอื่นๆ
เพิ่ม API ของ NDK
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 เพื่อสร้าง แต่เนื่องจากมีการสร้างไลบรารีไว้แล้ว คุณต้อง
ใช้ Flag 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 ของเวลาบิลด์ เช่น เมื่อเพิ่มไลบรารีที่สร้างไว้ล่วงหน้าซึ่งเป็น
ของ 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 หลายโปรเจ็กต์และรวมเอาต์พุตไว้ใน
คุณสามารถใช้ไฟล์ CMakeLists.txt 1 ไฟล์เป็น
สคริปต์บิลด์ 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 เพื่อสร้างโปรเจ็กต์นินจาภายนอก ของ 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
คำสั่งนี้จะสร้างโปรเจ็กต์นินจาที่สามารถเรียกใช้เพื่อสร้าง
ไลบรารีไฟล์ปฏิบัติการของ Android (.so ไฟล์) CMAKE_TOOLCHAIN_FILE คือ
ที่จำเป็นต่อการใช้การสนับสนุน CMake ของ NDK สำหรับ CMake 3.21 ขึ้นไปมี CMake ในตัว
สามารถใช้การรองรับ NDK แทนได้ แต่ต้องใช้ตัวแปรกลุ่มอื่น
ตามที่อธิบายไว้ในเอกสารประกอบการคอมไพล์ข้ามอุปกรณ์สำหรับ Android ของ CMake