CMake

Android NDK mendukung penggunaan CMake untuk mengompilasi kode C dan C++ bagi aplikasi Anda. Halaman ini membahas cara menggunakan CMake dengan NDK melalui ExternalNativeBuild Plugin Android Gradle atau ketika 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, dll. diberikan pada command line saat memanggil cmake. Untuk daftar argumen yang didukung, lihat bagian Argumen Toolchain.

Penggunaan

Gradle

Penggunaan file toolchain CMake dilakukan secara otomatis saat menggunakan externalNativeBuild. Lihat panduan Android Studio Menambahkan Kode C dan C++ ke Project Anda untuk mengetahui 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_NATIVE_API_LEVEL=$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 selalu mem-build dengan dukungan Neon, teruskan -DANDROID_ARM_NEON=TRUE.

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 -DANDROID_ABI=armeabi-v7a -DANDROID_ARM_NEON=ON.
arm64-v8a
x86
x86_64

ANDROID_ARM_MODE

Menentukan apakah akan membuat instruksi arm atau thumb bagi armeabi-v7a. Tidak berpengaruh bagi ABI lainnya. Untuk informasi selengkapnya, lihat dokumentasi ABI Android.

Nilai Catatan
arm
thumb Perilaku default.

ANDROID_ARM_NEON

Mengaktifkan atau menonaktifkan NEON untuk armeabi-v7a. Tidak berpengaruh bagi ABI lainnya. Ditetapkan secara default ke true untuk API level (minSdkVersion atau ANDROID_PLATFORM) 23 atau yang lebih baru, false untuk kondisi lainnya. Untuk informasi selengkapnya, lihat dokumentasi Neon.

Nilai Catatan
TRUE Default untuk API level 23 atau yang lebih baru.
FALSE Default untuk API level 22 atau yang lebih lama.

ANDROID_LD

Memilih linker yang akan digunakan. lld saat ini masih bersifat eksperimental untuk NDK dan dapat diaktifkan dengan argumen ini.

Nilai Catatan
lld Mengaktifkan lld.
default Gunakan linker default untuk ABI yang ditentukan.

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 terlebih dahulu argumen build spesifik yang digunakan Gradle saat melakukan kompilasi silang untuk Android.

Plugin Android Gradle menyimpan argumen build yang digunakannya untuk menjalankan build CMake bagi setiap pasangan ABI dan jenis build ke cmake_build_command.txt. File-file ini ditemukan dalam direktori berikut:

<project-root>/<module-root>/.cxx/cmake/<build-type>/<ABI>/

Cuplikan berikut ini menunjukkan contoh argumen CMake untuk mem-build rilis yang dapat di-debug dari contoh hello-jni yang menargetkan arsitektur armeabi-v7a.

Executable : ${HOME}/Android/Sdk/cmake/3.6.3155560/bin/cmake
arguments :
-H${HOME}/Dev/github-projects/googlesamples/android-ndk/hello-jni/app/src/main/cpp
-B${HOME}/Dev/github-projects/googlesamples/android-ndk/hello-jni/app/.cxx/cmake/arm7Debug/armeabi-v7a
-GAndroid Gradle - Ninja
-DANDROID_ABI=armeabi-v7a
-DANDROID_NDK=${HOME}/Android/Sdk/ndk-bundle
-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=${HOME}/Dev/github-projects/googlesamples/android-ndk/hello-jni/app/build/intermediates/cmake/arm7/debug/obj/armeabi-v7a
-DCMAKE_BUILD_TYPE=Debug
-DCMAKE_MAKE_PROGRAM=${HOME}/Android/Sdk/cmake/3.6.3155560/bin/ninja
-DCMAKE_TOOLCHAIN_FILE=${HOME}/Android/Sdk/ndk-bundle/build/cmake/android.toolchain.cmake
-DANDROID_NATIVE_API_LEVEL=23
-DANDROID_TOOLCHAIN=clang
jvmArgs :

Menggunakan library bawaan

Untuk mengetahui petunjuk tentang cara menggunakan library bawaan dengan CMake, lihat dokumentasi add_library tentang target IMPORTED dalam Panduan CMake.

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, lakukan perubahan berikut dalam CMakeLists.txt project Anda:

  1. Panggil enable_language dengan nilai yang ditetapkan ke ASM_NASM.
  2. Tergantung apakah Anda mem-build library bersama atau biner yang dapat dieksekusi, panggil add_library atau add_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 ini 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 executable, lihat pengujian yasm di repositori git NDK.

Melaporkan masalah

Jika Anda mengalami masalah dengan NDK atau file toolchain CMake-nya, laporkan melalui issue tracker android-ndk/ndk di GitHub.