הגדרת פרויקט

מגדירים פרויקט לשימוש בתוסף לפיתוח משחקים ל-Android.

התוסף לפיתוח משחקים ל-Android מפעיל את MSBuild כדי ליצור קוד מקור של C/C++ בספריות משותפות (.so) ובספריות סטטיות (.a). כחלק מתהליך ה-build, משימה מותאמת אישית של MSBuild מפעילה את Gradle כדי להדר קוד מקור של Java ו-Kotlin, לארוז נכסים וליצור קובץ APK לפריסה. כשמגדירים את הפרויקט, צריך לוודא של-MSBuild יש את המידע הדרוש ליצירת גרסה ל-Android.

פיתוח גרסאות build של C/C++ באמצעות MSBuild

פרויקט Android טיפוסי נוצר באמצעות Gradle, שבו הקוד המקורי בתוך הפרויקט נוצר על ידי סבב Gradle שמריץ את CMake או את ndk-build. באמצעות התוסף Android Game Development Extension ל-Visual Studio, תהליך ה-build הפוך. עכשיו MSBuild היא נקודת ההתחלה של תהליך ה-build. כל קוד המקור של C/C++ נוצר קודם על ידי MSBuild לפלטפורמות Android החדשות שמותקנות במערכת כחלק מהתוסף (לדוגמה, Android-x86_64). לאחר מכן, MSBuild מפעיל את Gradle כדי לארוז את קובצי הספרייה המשותפים שמכילים את הלוגיקה של C/C++ בקובץ APK.

קודם צריך לשכפל את הלוגיקה הקיימת של ה-build בפרויקט ב-CMake או ב-ndk-build ב-MSBuild. מגדירים את פלטפורמות היעד הבאות:

  • Android-x86
  • Android-x86_64
  • Android-armeabi-v7a
  • Android-arm64-v8a

כל הפלטפורמות האלה זמינות באמצעות התוסף Android Game Development Extension.

AGDE משתמש ב-NDK שבחרתם כדי לקבוע את אפשרויות ברירת המחדל לקישור ולקמפל כשמפתחים את החלק של האפליקציה ב-C/C++.

אם אתם צריכים להתאים אישית את אפשרויות הקישור או הידור הקוד, תוכלו להגדיר אותן באמצעות מאפייני הפרויקט. האפשרויות הנפוצות ביותר נמצאות בקבוצות C/C++‏ (לצורך הידור), Librarian (לצורך העברה לארכיון של ספריות סטטיות) ו-Linker (לצורך קישור של ספריות דינמיות). אם צריך להעביר אפשרויות בהתאמה אישית אחרות, אפשר להוסיף אותן לקטע Command Line. לדוגמה, אם אתם משתמשים ב-NDK מגרסה ישנה יותר מ-r28, כדאי להגדיר את הדגל של הקישור כדי שהאפליקציה תתמוך בדפים בגודל 16KB.

הוספת פלטפורמת Android

הפרויקט לדוגמה של Teapot כולל פלטפורמות Android, אבל צריך להוסיף באופן ידני פלטפורמת Android לפרויקט קיים. כדי להוסיף פלטפורמה חדשה, מבצעים את הפעולות הבאות ב-Visual Studio:

  1. בוחרים באפשרות Build > Configuration Manager.
  2. בקטע Active solution platform, בוחרים באפשרות <New>.

  3. מקלידים אחת מהאפשרויות הבאות לפלטפורמה החדשה:

    • Android-armeabi-v7a
    • Android-arm64-v8a
    • Android-x86
    • Android-x86_64

  4. בתיבה העתקת ההגדרות מ, בוחרים פלטפורמת Android קיימת אחרת או <ריקה> אם עדיין אין לכם פלטפורמות Android. מוודאים שהפעלתם את האפשרות Create new project platforms.

הוספת פריט APK ל-Android

בוחרים באפשרות Add (הוספה) > New Item (פריט חדש) > Visual C++‏ > Android‏ > Android APK ולוחצים על Add (הוספה). מגדירים את אפליקציית Android בתיבת הדו-שיח הבאה.

  • שם האפליקציה: השם של האפליקציה ל-Android שקריא לבני-אדם.
  • מזהה האפליקציה: המזהה הייחודי של האפליקציה ל-Android.
  • מיקום ב-Solution Explorer: המיקום של התיקייה הווירטואלית שמכילה את קובצי התמיכה הנוספים לחבילות ל-Android. כברירת מחדל, הקבצים האלה נמצאים גם בפרויקט בתיקייה עם אותו שם. כדי להתאים אישית את המיקום, מסמנים את התיבה Put support files in a custom location ומציינים מיקום מותאם אישית. התיקייה הווירטואלית עדיין תופיע בפרויקט הנוכחי ב-Solution Explorer.

איך גורמים ל-MSBuild להפעיל את Gradle כדי ליצור קובץ APK

MSBuild לא יכול להפעיל את Gradle אלא אם הוא יודע את המיקום של פרויקט Gradle. מגדירים את המיקום הזה באמצעות המאפיין Gradle Build Directory, כפי שמוצג באיור 1.


איור 1. המאפיין Gradle Build Directory

בנוסף, מגדירים את המאפיינים Application Module,‏ Application Variant ו-APK Name (כפי שמוצג בתמונה הקודמת) כדי ש-MSBuild ידע מה ליצור.

  • Application Module: השם של פרויקט המשנה ב-Gradle. זהו הפרויקט הראשי שמוגדר בקובץ settings.gradle. בדרך כלל השם שלו הוא app בפרויקטים שנוצרו ישירות באמצעות Android Studio.
  • Application Variant: הווריאנט של Android ליצירת build. צריך להגדיר את הערך הזה בהתאם להגדרות של MSBuild. לדוגמה, ל-build לצורך ניפוי באגים צריך להגדיר ערך לווריאנט לניפוי באגים. אם שם התצורה של הפרויקט ב-MSBuild תואם לשמות הווריאנטים ב-Gradle, אפשר פשוט להשתמש בערך ברירת המחדל $(Configuration).
  • שם קובץ ה-APK: השם של קובץ ה-APK שנוצר, שמשמש לניפוי באגים וליצירת פרופיל במחשב הפיתוח. השם הזה מועבר ל-Gradle, וסקריפט ה-build של Gradle צריך להתייחס אליו (ראו את המאפיין MSBUILD_ANDROID_OUTPUT_APK_NAME בקטע הבא).

שינוי של סקריפטים ל-build ב-Gradle

במהלך ה-build, MSBuild מעביר את המידע הבא כמאפייני פרויקט לסקריפט Gradle. משנים את סקריפט ה-build הקיים של הפרויקט (בדרך כלל נקרא build.gradle) כך שיקריא את המאפיינים האלה.

  • MSBUILD_MIN_SDK_VERSION: גרסת ה-SDK המינימלית ליצירת קובץ ה-APK. מגדירים את הערך הזה בתיבה גרסת Android SDK מינימלית בדף של מאפייני הפרויקט שמוצג באיור 2.


    איור 2. המאפיין Minimum Android SDK Version

    סקריפט ה-build של Gradle צריך להגדיר את minSdkVersion לערך הזה, כפי שמוצג בהמשך.

    Groovy

    android {
  // ...

  defaultConfig {
      applicationId "com.yourcompany.yourapp"
      minSdkVersion MSBUILD_MIN_SDK_VERSION
      // ...
  }

  // ...
}

    Kotlin

    android {
  // ...

  defaultConfig {
      applicationId = "com.yourcompany.yourapp"
      minSdkVersion(MSBUILD_MIN_SDK_VERSION)
      // ...
  }

  // ...
}

  • MSBUILD_ANDROID_OUTPUT_APK_NAME: השם הצפוי של קובץ ה-APK ש-Gradle יוצר. התוסף Android Game Development Extension יחפש קובץ APK שתואם לשם הזה, ולאחר מכן פורס אותו במכשירים מחוברים (לצורך ניפוי באגים וליצור פרופיל). מגדירים את הערך הזה בתיבה APK Name בדף של מאפיין הפרויקט שמוצג באיור 3.


    איור 3. המאפיין APK Name

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

    Groovy

    android {
  // ...

  applicationVariants.all { variant ->
      variant.outputs.all {
          outputFileName = MSBUILD_ANDROID_OUTPUT_APK_NAME
      }
  }

  // ...
}

    Kotlin

    android {
  // ...

  applicationVariants.all { variant ->
      variant.outputs.all {
          outputFileName = MSBUILD_ANDROID_OUTPUT_APK_NAME
      }
  }

  // ...
}

  • MSBUILD_JNI_LIBS_SRC_DIR: התיקייה שמכילה את הספריות המשותפות (קבצי .so) שנוצרו על ידי MSBuild. מגדירים את הערך הזה בתיבה Output Directory בדף של מאפיין הפרויקט שמוצג בהמשך. כברירת מחדל, הערך הזה הוא מאפיין ספריית הפלט של הפרויקט ב-Visual Studio, כפי שמוצג באיור 4.


    איור 4. המאפיין Output Directory

    Gradle צריך לארוז את קובצי הספרייה המשותפת בתיקייה הזו בתוך קובץ ה-APK, כדי שאפליקציית Android תוכל לטעון אותם בזמן הריצה.

    Groovy

    android {
  // ...

  sourceSets {
      main {
          jniLibs.srcDirs += [MSBUILD_JNI_LIBS_SRC_DIR]
      }
  }

  // ...
}

    Kotlin

    android {
  // ...

  sourceSets.getByName("main") {
      jniLibs.srcDir(MSBUILD_JNI_LIBS_SRC_DIR)
  }

  // ...
}

    בנוסף, מאחר שכל קוד C/C++ נוצר עכשיו על ידי MSBuild, צריך להסיר את הקטעים externalNativeBuild בסקריפטים של ה-build ב-Gradle. הקטעים האלה שימשו להפעלת CMake או ndk-build כדי לקמפל את קוד ה-C/C++ שלכם, אבל הם כבר לא נחוצים.

  • MSBUILD_NDK_VERSION: הגרסה של NDK שבה משתמשים כדי ליצור את הפרויקט. מגדירים את הערך הזה בתיבה Android NDK Version בדף של מאפיין הפרויקט שמוצג באיור 5.


    איור 5. המאפיין Android NDK Version

    סקריפט ה-build של Gradle צריך להגדיר את ndkVersion לערך הזה, כפי שמוצג:

    Groovy

    android {
  // ...

  ndkVersion MSBUILD_NDK_VERSION

  // ...
}

    Kotlin

    android {
  // ...

  ndkVersion = MSBUILD_NDK_VERSION

  // ...
}

    למידע נוסף, ראו את המאמר בנושא Android Studio התקנה והגדרה של NDK ו-CMake.