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.
פרמטרים של גרסת build כמו ABI, minSdkVersion וכו' ניתנים בשורת הפקודה כשמפעילים את cmake. רשימה של הארגומנטים הנתמכים מופיעה בקטע ארגומנטים של Toolchain.
קובץ ה-toolchain "החדש"
בגרסאות קודמות של NDK, ניסינו הטמעה חדשה של קובץ ה-toolchain כדי לצמצם את ההבדלים בהתנהגות בין שימוש בקובץ ה-toolchain של NDK לבין שימוש בתמיכה המובנית ב-CMake. התהליך הזה דרש הרבה עבודה (שלא הושלמה), אבל לא באמת שיפר את ההתנהגות, אז הפסקנו לעבוד על זה.
בקובץ ה-toolchain "החדש" יש רגרסיות בהתנהגות בהשוואה לקובץ ה-toolchain "הקודם". פעולת ברירת המחדל היא תהליך העבודה המומלץ. אם אתם משתמשים ב--DANDROID_USE_LEGACY_TOOLCHAIN_FILE=OFF, מומלץ להסיר את הדגל הזה מה-build. קובץ ה-toolchain החדש לא הגיע לשוויון עם קובץ ה-toolchain הקודם, ולכן סביר להניח שיש רגרסיות בהתנהגות.
אנחנו ממליצים לא להשתמש בקובץ ה-toolchain החדש, אבל כרגע אין לנו תוכניות להסיר אותו מה-NDK. אם נעשה את זה, זה יפגע בגרסאות build שמסתמכות על ההבדלים בהתנהגות בין קובצי ה-toolchain החדשים והקודמים. לצערנו, גם שינוי השם של האפשרות כדי להבהיר שמומלץ להשתמש ב-"legacy" יפגע במשתמשים באפשרות הזו. אם אתם משתמשים בקובץ ה-toolchain החדש ואין לכם בעיות, אתם לא צריכים לעבור, אבל חשוב לדעת שבאגים שקשורים להתנהגות של קובץ ה-toolchain החדש כנראה לא יתוקנו, ובמקום זאת תצטרכו לעבור.
שימוש
Gradle
השימוש בקובץ ה-toolchain של CMake הוא אוטומטי כשמשתמשים ב-externalNativeBuild. מידע נוסף זמין במדריך הוספת קוד C ו-C++ לפרויקט של Android Studio.
שורת פקודה
כשמפתחים באמצעות CMake מחוץ ל-Gradle, צריך להעביר ל-CMake את קובץ ה-toolchain עצמו ואת הארגומנטים שלו. לדוגמה:
$ 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 יוצר גרסאות build ליעד אחד בכל build. כדי לטרגט ליותר מ-ABI אחד של Android, צריך ליצור build אחד לכל ABI. מומלץ להשתמש בספריות build שונות לכל ABI כדי למנוע התנגשויות בין גרסאות build.
| ערך | הערות |
|---|---|
armeabi-v7a |
|
armeabi-v7a with NEON |
בדיוק כמו במכשיר armeabi-v7a. |
arm64-v8a |
|
x86 |
|
x86_64 |
ANDROID_ARM_MODE
מציינת אם ליצור הוראות arm או thumb עבור armeabi-v7a. אין השפעה על ממשקי ABI אחרים. מידע נוסף זמין במסמכי התיעוד בנושא ממשקי ABI של Android.
| ערך | הערות |
|---|---|
| קבוצה | |
| אגודל | פעולת ברירת מחדל. |
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_LEVELandroid-$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) של ה-build, עיינו במסמכי התיעוד של CMake בנושא set_target_compile_options וקבוצת האפשרויות הקשורה. בקטע "ראו גם" בתחתית הדף יש כמה רמזים מועילים.
באופן כללי, השיטה המומלצת היא להחיל דגלי קומפיילר בהיקף הצר ביותר שזמין. לא נוח לחזור על דגלים שרוצים להחיל על כל היעדים (כמו -Werror) בכל מודול, אבל עדיין כדאי להחיל אותם באופן גלובלי (CMAKE_CXX_FLAGS) רק לעיתים רחוקות, כי יכולות להיות להם השפעות לא רצויות על יחסי תלות של צד שלישי בפרויקט. במקרים כאלה, אפשר להחיל את הדגלים ברמת הספרייה (add_compile_options).
לקבוצת משנה צרה של דגלי קומפיילר, אפשר גם להגדיר אותם בקובץ build.gradle באמצעות cppFlags או מאפיינים דומים. אל תעשו את זה. דגלים שמועברים ל-CMake מ-Gradle יקבלו קדימויות מפתיעות, ובמקרים מסוימים יעקפו דגלים שמועברים באופן משתמע על ידי ההטמעה שנדרשת לבניית קוד Android. תמיד עדיף לטפל בהתנהגות של CMake ישירות ב-CMake. אם אתם צריכים לשלוט בדגלי קומפיילר לכל AGP buildType, עיינו במאמר עבודה עם סוגי build של AGP ב-CMake.
עבודה עם סוגי build של AGP ב-CMake
אם אתם צריכים להתאים את ההתנהגות של CMake ל-buildType מותאם אישית של Gradle, השתמשו בסוג ה-build הזה כדי להעביר דגל CMake נוסף (לא דגל קומפיילר) שסקריפטים של ה-build של CMake יכולים לקרוא. לדוגמה, אם יש לכם וריאנטים של build מסוג "חינמי" ו "פרימיום" שנשלטים על ידי 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 של Sanitizers.
הסבר על פקודת ה-build של CMake
כשמנפים באגים בבעיות שקשורות ל-CMake build, כדאי לדעת מהם הארגומנטים הספציפיים של ה-build שבהם Gradle משתמש במהלך עיבוד בין מערכות ל-Android.
הפלאגין של Android Gradle שומר את הארגומנטים של ה-build שבהם הוא משתמש כדי להפעיל build של CMake לכל זוג של ABI וסוג build ב-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, אתם יכולים לייבא אותה ולהשתמש בה לפי המסמכים של Studio בנושא יחסי תלות. אם אתם לא משתמשים ב-AGP, אתם יכולים לפעול לפי ההוראות בכתובת https://google.github.io/prefab/example-workflow.html, אבל כנראה יהיה לכם הרבה יותר קל לעבור ל-AGP.
אם אתם משתמשים בספריות שלא מופצות כ-AAR, אתם יכולים לקרוא הוראות לשימוש בספריות מוכנות מראש עם CMake במסמכי התיעוד של add_library בנושא יעדי IMPORTED במדריך של CMake.
בניית קוד של צד שלישי
יש כמה דרכים לבנות קוד של צד שלישי כחלק מפרויקט CMake, והאפשרות הכי טובה תלויה במצב שלכם. בדרך כלל, האפשרות הטובה ביותר היא לא לעשות את זה בכלל. במקום זאת, צרו AAR לספרייה והשתמשו בו באפליקציה. לא חייבים לפרסם את ה-AAR הזה. הוא יכול להיות פנימי לפרויקט Gradle.
אם זה לא אפשרי:
- יוצרים עותק מקוד של צד שלישי (vendoring) במאגר ומשתמשים ב-add_subdirectory כדי ליצור אותו. זה עובד רק אם הספרייה השנייה גם נוצרה באמצעות CMake.
- מגדירים ExternalProject.
- מפתחים גרסת build של הספרייה בנפרד מהפרויקט ופועלים לפי ההוראות במאמר שימוש בספריות מוכנות מראש כדי לייבא אותה כספרייה מוכנה מראש.
תמיכה ב-YASM ב-CMake
ה-NDK מספק תמיכה ב-CMake ליצירת קוד אסמבלי שנכתב ב-YASM כדי לפעול בארכיטקטורות x86 ו-x86-64. YASM הוא אסמבלר בקוד פתוח לארכיטקטורות x86 ו-x86-64, שמבוסס על האסמבלר NASM.
כדי ליצור קוד אסמבלי באמצעות CMake, מבצעים את השינויים הבאים בקובץ CMakeLists.txt של הפרויקט:
- מפעילים את
enable_languageכשהערך מוגדר ל-ASM_NASM. - בהתאם לסוג הקובץ שאתם יוצרים, ספרייה משותפת או קובץ בינארי להפעלה, קוראים לפונקציה
add_libraryאוadd_executable. בארגומנטים, מעבירים רשימה של קובצי מקור שמורכבת מקובצי.asmלתוכנית ה-assembly ב-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.