CMake

‫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_LEVEL
  • android-$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 של הפרויקט:

  1. מפעילים את enable_language כשהערך מוגדר ל-ASM_NASM.
  2. בהתאם לסוג הקובץ שאתם יוצרים, ספרייה משותפת או קובץ בינארי להפעלה, קוראים לפונקציה 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.