הגדרת CMake

סקריפט build של CMake הוא קובץ טקסט פשוט שצריך לקרוא לו CMakeLists.txt, והוא כולל פקודות שמשמשות את CMake כדי ליצור את ספריות C/C++‎. אם למקורות המקומיים עדיין אין סקריפט build של CMake, צריך ליצור סקריפט כזה ולכלול את פקודות ה-CMake המתאימות. במאמר התקנה והגדרה של NDK ו-CMake מוסבר איך להתקין את CMake.

בקטע הזה נסביר על כמה פקודות בסיסיות שצריך לכלול בסקריפט ה-build כדי להורות ל-CMake באילו מקורות להשתמש כשיוצרים את ספריית ה-Native. מידע נוסף זמין במסמכי התיעוד הרשמיים בנושא פקודות CMake.

אחרי שמגדירים סקריפט build חדש של CMake, צריך להגדיר את Gradle כך שיכלול את פרויקט ה-CMake כתלות של ה-build, כדי ש-Gradle יבנה את ספריית ה-Native ויארוז אותה עם ה-APK של האפליקציה.

הערה: אם הפרויקט משתמש ב-ndk-build, אין צורך ליצור סקריפט build של CMake. אתם יכולים פשוט להגדיר את Gradle כך שיכלול את הפרויקט הקיים של ספריית ה-Native, על ידי ציון הנתיב לקובץ Android.mk.

יצירת סקריפט build של CMake

כדי ליצור קובץ טקסט פשוט שאפשר להשתמש בו כסקריפט ה-build של CMake:

  1. פותחים את החלונית Project בצד שמאל של ה-IDE ובוחרים בתצוגה Project בתפריט הנפתח.
  2. לוחצים לחיצה ימנית על תיקיית השורש של your-module ובוחרים באפשרות New > File.

    הערה: אפשר ליצור את הסקריפט של ה-build בכל מיקום שרוצים. עם זאת, כשמגדירים את סקריפט ה-build, הנתיבים לקובצי המקור ולספריות המקור הם יחסיים למיקום של סקריפט ה-build.

  3. מזינים את שם הקובץ "CMakeLists.txt" ולוחצים על OK.

עכשיו אפשר להגדיר את סקריפט ה-build על ידי הוספת פקודות CMake. כדי להורות ל-CMake ליצור ספריית Native מקוד מקור של Native, מוסיפים את הפקודות cmake_minimum_required() ו-add_library() לסקריפט ה-build:

# 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 ליצור ספריית Native מקובצי מקור, אפשר להשתמש בפקודה add_executable() כדי להורות ל-CMake ליצור קובץ הפעלה מקובצי המקור האלה. עם זאת, לא חובה ליצור קובצי הפעלה ממקורות ה-Native, ויצירת ספריות Native לאריזה ב-APK עונה על רוב דרישות הפרויקט.

כשמוסיפים קובץ מקור או ספרייה לסקריפט ה-build של CMake באמצעות add_library(), קובצי הכותרת המשויכים מוצגים גם בתצוגה Project ב-Android Studio אחרי שמסנכרנים את הפרויקט. עם זאת, כדי ש-CMake יאתר את קובצי הכותרת במהלך הקימפול, צריך להוסיף את הפקודה include_directories() לסקריפט ה-build של CMake ולציין את הנתיב לכותרות:

add_library(...)

# Specifies a path to native header files.
include_directories(src/main/cpp/include/)

המוסכמה של CMake למתן שמות לקובץ של הספרייה היא:

liblibrary-name.so

לדוגמה, אם מציינים את השם "native-lib" לספרייה המשותפת בסקריפט ה-build, ‏CMake יוצר קובץ בשם libnative-lib.so. עם זאת, כשאתם טוענים את הספרייה הזו בקוד Java או Kotlin, אתם צריכים להשתמש בשם שציינתם בסקריפט ה-build של CMake:

companion object {
    init {
        System.loadLibrary("native-lib")
    }
}

הערה: אם משנים את השם של ספרייה או מסירים אותה בסקריפט ה-build של CMake, צריך לנקות את הפרויקט לפני ש-Gradle יחיל את השינויים או יסיר את הגרסה הישנה של הספרייה מה-APK. כדי לנקות את הפרויקט, בסרגל התפריטים לוחצים על Build > Clean Project.

‫Android Studio מוסיף באופן אוטומטי את קובצי המקור והכותרות לקבוצת cpp בחלונית Project. באמצעות כמה פקודות add_library(), אתם יכולים להגדיר ספריות נוספות ל-CMake כדי ליצור מקובצי מקור אחרים.

הוספת ממשקי API של NDK

‫Android NDK מספק קבוצה של ממשקי API וספריות מקומיים שיכולים להיות שימושיים. כדי להשתמש בכל אחד מממשקי ה-API האלה, צריך לכלול את ספריות ה-NDK בקובץ הסקריפט CMakeLists.txt של הפרויקט.

ספריות NDK שנוצרו מראש כבר קיימות בפלטפורמת Android, כך שאתם לא צריכים ליצור אותן או לארוז אותן ב-APK. מכיוון שספריות ה-NDK כבר נמצאות בנתיב החיפוש של CMake, אתם לא צריכים לציין את המיקום של הספרייה בהתקנת ה-NDK המקומית שלכם. אתם רק צריכים לספק ל-CMake את שם הספרייה שבה אתם רוצים להשתמש ולקשר אותה לספריית ה-Native שלכם.

מוסיפים את הפקודה find_library() לסקריפט ה-build של CMake כדי לאתר ספריית NDK ולשמור את הנתיב שלה כמשתנה. המשתנה הזה משמש כדי להפנות לספריית ה-NDK בחלקים אחרים של סקריפט ה-build. בדוגמה הבאה, המערכת מאתרת את ספריית התמיכה ביומנים שספציפית ל-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 )

כדי שספריית ה-Native תוכל לקרוא לפונקציות בספרייה log, צריך לקשר את הספריות באמצעות הפקודה target_link_libraries() בסקריפט ה-build של 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 כולל גם כמה ספריות כקוד מקור שצריך ליצור ולקשר לספריית ה-Native. כדי לקמפל את קוד המקור לספריית Native, אפשר להשתמש בפקודה add_library() בסקריפט ה-build של 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} )

הוספת ספריות אחרות שנוצרו מראש

הוספת ספרייה מוכנה מראש דומה לציון ספריית Native אחרת ש-CMake צריך ליצור. עם זאת, מכיוון שהספרייה כבר נוצרה, צריך להשתמש בדגל IMPORTED כדי להורות ל-CMake שרוצים לייבא את הספרייה רק לפרויקט:

add_library( imported-lib
             SHARED
             IMPORTED )

לאחר מכן צריך לציין את הנתיב לספרייה באמצעות הפקודה set_target_properties(), כמו שמוצג בהמשך.

חלק מהספריות מספקות חבילות נפרדות לארכיטקטורות ספציפיות של מעבדים (CPU) או ממשקי Application Binary Interface‏ (ABI), ומארגנות אותן בספריות נפרדות. הגישה הזו עוזרת לספריות לנצל ארכיטקטורות מסוימות של מעבדים (CPU), ומאפשרת לכם להשתמש רק בגרסאות של הספרייה שאתם רוצים. כדי להוסיף כמה גרסאות ABI של ספרייה לסקריפט ה-build של 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/ )

הערה: אם רוצים לארוז ספרייה מוכנה מראש שהיא לא תלות בזמן ה-build – לדוגמה, כשמוסיפים ספרייה מוכנה מראש שהיא תלות של imported-lib, לא צריך לבצע את ההוראות הבאות כדי לקשר את הספרייה.

כדי לקשר את הספרייה המוגדרת מראש לספריית ה-Native שלכם, מוסיפים אותה לפקודה target_link_libraries() בסקריפט ה-build של CMake:

target_link_libraries( native-lib imported-lib app-glue ${log-lib} )

כדי לארוז את הספרייה המוגדרת מראש ב-APK, צריך להגדיר את Gradle באופן ידני באמצעות הבלוק sourceSets כדי לכלול את הנתיב לקובץ .so. אחרי שיוצרים את ה-APK, אפשר להשתמש בכלי לניתוח APK כדי לבדוק אילו ספריות Gradle אורזת ב-APK.

הוספת פרויקטים אחרים של CMake

אם אתם רוצים ליצור כמה פרויקטים של CMake ולכלול את הפלט שלהם בפרויקט Android, אתם יכולים להשתמש בקובץ CMakeLists.txt אחד בתור סקריפט ה-build של CMake ברמה העליונה (זה שמקשרים ל-Gradle) ולהוסיף עוד פרויקטים של CMake כתלויות של סקריפט ה-build הזה. סקריפט ה-build של CMake ברמה העליונה משתמש בפקודה add_subdirectory() כדי לציין קובץ CMakeLists.txt אחר כתלות ב-build, ואז מקשר לפלט שלו בדיוק כמו שהיה עושה עם כל ספרייה אחרת שנוצרה מראש.

# 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 וליצור פרויקט Ninja מחוץ ל-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

הפקודה הזו תיצור את פרויקט Ninja שאפשר להריץ כדי ליצור ספריות הפעלה של Android (קובצי .so). כדי להשתמש בתמיכה של NDK ב-CMake, צריך את CMAKE_TOOLCHAIN_FILE. ב-CMake מגרסה 3.21 ואילך, אפשר להשתמש בתמיכה המובנית של CMake ב-NDK, אבל צריך להשתמש בקבוצה אחרת של משתנים, כמו שמתואר במסמכי התיעוד של CMake בנושא עיבוד בין מערכות ל-Android.