Android NDK mendukung penggunaan CMake untuk
mengompilasi kode C dan C++ untuk aplikasi. Halaman ini membahas cara menggunakan
CMake dengan NDK melalui ExternalNativeBuild
Plugin Android Gradle atau saat
memanggil CMake secara langsung.
File toolchain CMake
NDK mendukung CMake melalui file toolchain. File Toolchain adalah file CMake yang menyesuaikan perilaku toolchain untuk kompilasi silang. File toolchain yang digunakan untuk NDK terletak dalam NDK di <NDK>/build/cmake/android.toolchain.cmake
.
Parameter build seperti ABI, minSdkVersion
, dsb. diberikan pada command
line saat memanggil cmake
. Untuk daftar argumen yang didukung, lihat
bagian Argumen toolchain.
"Baru" file toolchain
NDK sebelumnya bereksperimen dengan implementasi baru file toolchain yang akan mengurangi perbedaan perilaku antara menggunakan file toolchain NDK dan menggunakan dukungan CMake bawaan. Sistem ini akhirnya membutuhkan jumlah pekerjaan (yang belum selesai), tetapi tidak benar-benar meningkatkan perilaku, jadi kita tidak lagi mengejar hal ini.
"Baru" file toolchain memiliki regresi perilaku dibandingkan dengan "lama"
file toolchain tersebut. Perilaku default adalah alur kerja yang direkomendasikan. Jika Anda
menggunakan -DANDROID_USE_LEGACY_TOOLCHAIN_FILE=OFF
, sebaiknya hapus flag tersebut
dari build Anda. File toolchain baru tidak pernah mencapai paritas dengan versi lama
, sehingga kemungkinan ada regresi perilaku.
Meskipun kami menyarankan untuk tidak menggunakan file toolchain baru, saat ini tidak ada berencana menghapusnya dari NDK. Tindakan ini akan merusak build yang bergantung pada perbedaan perilaku antara file toolchain baru dan lama, dan sayangnya mengganti nama opsi untuk memperjelas bahwa "lama" sebenarnya juga akan merugikan pengguna opsi tersebut. Jika Anda dengan senang hati menggunakan file toolchain baru yang tidak perlu Anda migrasikan, tetapi ketahuilah bahwa ada bug yang terhadap perilaku file toolchain baru mungkin tidak akan diperbaiki, dan sebagai gantinya yang harus Anda migrasikan.
Penggunaan
Gradle
Penggunaan file toolchain CMake dilakukan otomatis saat menggunakan
externalNativeBuild
. Lihat panduan Android Studio tentang Menambahkan kode C dan C++ ke
project untuk informasi selengkapnya.
Command Line
Saat mem-build dengan CMake di luar Gradle, file toolchain tersebut sendiri beserta argumennya harus diteruskan ke CMake. Contoh:
$ cmake \
-DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \
-DANDROID_ABI=$ABI \
-DANDROID_PLATFORM=android-$MINSDKVERSION \
$OTHER_ARGS
Argumen toolchain
Argumen berikut dapat diteruskan ke file toolchain CMake. Jika mem-build dengan Gradle, tambahkan argumen ke android.defaultConfig.externalNativeBuild.cmake.arguments
seperti yang dijelaskan dalam dokumen ExternalNativeBuild. Jika mem-build dari command line, teruskan argumen ke CMake dengan -D
. Misalnya, untuk memaksa armeabi-v7a agar tidak membangun dengan Neon
berikan dukungan, teruskan -DANDROID_ARM_NEON=FALSE
.
ANDROID_ABI
ABI target. Untuk informasi tentang ABI yang didukung, lihat ABI Android.
Gradle
Gradle memberikan argumen ini secara otomatis. Jangan tetapkan argumen ini secara eksplisit dalam file build.gradle
Anda. Untuk mengontrol ABI yang ditargetkan Gradle, gunakan abiFilters
seperti yang dijelaskan dalam ABI Android.
Command Line
CMake melakukan proses build untuk satu target per build. Untuk menargetkan lebih dari satu ABI Android, Anda harus melakukan proses build satu kali per ABI. Sebaiknya gunakan direktori build yang berbeda untuk setiap ABI guna menghindari konflik antar-build.
Nilai | Catatan |
---|---|
armeabi-v7a |
|
armeabi-v7a with NEON |
Sama seperti armeabi-v7a . |
arm64-v8a |
|
x86 |
|
x86_64 |
ANDROID_ARM_MODE
Menentukan apakah akan membuat instruksi arm atau thumb untuk armeabi-v7a. Tidak berpengaruh bagi ABI lainnya. Untuk informasi selengkapnya, lihat dokumentasi ABI Android.
Nilai | Catatan |
---|---|
arm | |
thumb | Perilaku default. |
ANDROID_NATIVE_API_LEVEL
Alias untuk ANDROID_PLATFORM.
ANDROID_PLATFORM
Menetapkan API level minimum yang didukung oleh aplikasi atau library. Nilai ini terkait dengan minSdkVersion
aplikasi.
Gradle
Saat menggunakan Plugin Android Gradle, nilai ini otomatis ditetapkan agar cocok dengan minSdkVersion
aplikasi dan tidak boleh ditetapkan secara manual.
Command Line
Saat memanggil CMake secara langsung, nilai ini ditetapkan secara default ke API level terendah yang didukung oleh NDK yang sedang digunakan. Misalnya, dengan NDK r20, nilai ini ditetapkan secara default ke API level 16.
Beberapa format diterima untuk parameter ini:
android-$API_LEVEL
$API_LEVEL
android-$API_LETTER
Format $API_LETTER
memungkinkan Anda untuk menetapkan android-N
tanpa perlu menentukan nomor yang terkait dengan rilis tersebut. Perlu diketahui bahwa beberapa rilis menerima peningkatan API tanpa peningkatan huruf. API ini dapat ditentukan dengan menambahkan akhiran -MR1
. Misalnya, API level 25 adalah android-N-MR1
.
ANDROID_STL
Menetapkan STL yang akan digunakan untuk aplikasi ini. Untuk informasi selengkapnya, lihat Dukungan
library C++. Secara default, c++_static
akan digunakan.
Nilai | Catatan |
---|---|
c++_shared | Varian library bersama libc ++. |
c++_static | Varian library statis libc ++. |
none | Tidak ada dukungan library standar C++. |
system | STL sistem |
Memahami perintah build CMake
Saat men-debug masalah build CMake, sebaiknya ketahui argumen build spesifik yang digunakan Gradle saat mengompilasi silang untuk Android.
Plugin Android Gradle menyimpan argumen build yang digunakannya untuk menjalankan
build CMake untuk setiap pasangan ABI dan pasangan
jenis build ke build_command.txt
. File-file ini ditemukan dalam direktori
berikut:
<project-root>/<module-root>/.cxx/cmake/<build-type>/<ABI>/
Cuplikan berikut menunjukkan contoh argumen CMake untuk mem-build
rilis contoh hello-jni
yang dapat di-debug dan menargetkan
arsitektur 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
Menggunakan library bawaan
Jika library bawaan yang perlu Anda impor didistribusikan sebagai AAR, ikuti dokumen dependensi Studio untuk mengimpor dan menggunakannya. Jika tidak menggunakan AGP, Anda dapat mengikuti https://google.github.io/prefab/example-workflow.html, tetapi kemungkinan akan lebih mudah untuk bermigrasi ke AGP.
Untuk library yang tidak didistribusikan sebagai AAR, lihat petunjuk tentang cara menggunakan library
bawaan dengan CMake, lihat dokumentasi add_library
terkait target
IMPORTED
dalam Panduan CMake.
Membuat kode pihak ketiga
Ada beberapa cara untuk membuat kode pihak ketiga sebagai bagian dari project CMake Anda, dan opsi mana yang berfungsi paling baik bergantung pada situasi Anda. Opsi terbaik sering kali adalah tidak melakukan ini sama sekali. Sebagai gantinya, build AAR untuk library dan gunakan di aplikasi Anda. Anda tidak perlu memublikasikan AAR tersebut. AAR dapat bersifat internal untuk project Gradle Anda.
Jika tidak dapat dilakukan:
- Lakukan vendoring (misalnya, salin) sumber pihak ketiga ke dalam repositori Anda dan gunakan add_subdirectory untuk mem-build. Ini hanya berfungsi jika library lain juga di-build dengan CMake.
- Tentukan ExternalProject.
- Build library secara terpisah dari project Anda dan ikuti Menggunakan library bawaan untuk mengimpornya sebagai bawaan.
Dukungan YASM di CMake
NDK menyediakan dukungan CMake untuk mem-build kode penggabungan yang ditulis dalam YASM agar dapat dijalankan pada arsitektur x86 dan x86-64. YASM adalah assembler open source untuk arsitektur x86 dan x86-64, yang didasarkan pada assembler NASM.
Untuk mem-build kode penggabungan dengan CMake, buat perubahan berikut dalam CMakeLists.txt
project:
- Panggil
enable_language
dengan nilai yang ditetapkan keASM_NASM
. - Bergantung pada apakah Anda mem-build library bersama atau biner yang dapat
dieksekusi, panggil
add_library
atauadd_executable
. Dalam argumen, teruskan daftar file sumber yang terdiri dari file.asm
untuk program penggabungan di YASM dan file.c
untuk fungsi atau library C terkait.
Cuplikan berikut menunjukkan cara mengonfigurasi CMakeLists.txt
untuk
mem-build program YASM sebagai library bersama.
cmake_minimum_required(VERSION 3.6.0)
enable_language(ASM_NASM)
add_library(test-yasm SHARED jni/test-yasm.c jni/print_hello.asm)
Untuk mengetahui contoh tentang cara mem-build program YASM sebagai file yang dapat dieksekusi, lihat pengujian yasm di repositori git NDK.
Melaporkan masalah
Jika Anda mengalami masalah terkait NDK atau file toolchain CMake-nya, laporkan melalui issue tracker android-ndk/ndk di GitHub. Untuk masalah Gradle atau Plugin Android Gradle, laporkan bug Studio.