Mengonfigurasi project

Mengonfigurasi project untuk menggunakan Android Game Development Extension

Android Game Development Extension memanggil MSBuild untuk mem-build kode sumber C/C++ menjadi library bersama (.so) dan library statis (.a). Sebagai bagian dari proses build, tugas MSBuild kustom memanggil Gradle untuk mengompilasi kode sumber Java dan Kotlin, aset paket, dan menghasilkan file APK untuk deployment. Saat mengonfigurasi project, Anda harus memastikan bahwa MSBuild memiliki informasi yang diperlukan untuk membuat platform Android.

Mem-build C/C++ dengan MSBuild

Project Android biasa dibuat dengan Gradle. Di dalam project, kode native dibuat oleh penerusan Gradle yang menjalankan CMake atau ndk-build. Dengan Android Game Development Extension untuk Visual Studio, proses build akan dibalik. Kini MSBuild adalah titik awal proses build. Semua kode sumber C/C++ dibangun terlebih dahulu oleh MSBuild untuk Platform Android yang diinstal di sistem Anda sebagai bagian dari ekstensi (untuk misalnya, "Android-x86_64"). MSBuild kemudian memanggil Gradle untuk memaketkan file library bersama yang berisi logika C/C++ ke dalam APK.

Anda harus terlebih dahulu mereplikasi logika build yang ada di CMake atau ndk-build di MSBuild. Tetapkan platform target ke berikut ini:

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

Semua platform ini disediakan oleh Android Game Development Extension.

Menambahkan Platform Android

Meskipun project contoh teapot mencakup platform Android, Anda harus menambahkan platform Android secara manual ke project yang sudah ada. Untuk menambahkan platform baru, lakukan hal berikut di Visual Studio:

  1. Pilih Build > Configuration Manager.
  2. Di bagian Active solution platform, pilih <New>.

  3. Ketik salah satu dari berikut ini untuk platform baru:

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

  4. Di kotak Copy settings from, pilih perangkat Android lain yang sudah ada platform Android, atau <Empty> jika Anda belum memiliki platform Android. Pastikan Anda telah mengaktifkan opsi Create new project platform.

Menambahkan item APK Android

Pilih Tambahkan > Item Baru > C++ Visual > Android > APK Android dan klik Tambahkan. Konfigurasikan aplikasi Android pada dialog berikut.

  • Application Name: Nama aplikasi Android yang dapat dibaca manusia.
  • Application ID: ID unik untuk aplikasi Android Anda.
  • Solution Explorer Location: Lokasi folder virtual yang berisi file dukungan paket Android yang ditambahkan. Secara default, file ini juga berada di project dalam folder dengan nama yang sama. Anda dapat menyesuaikan dengan memilih Tempatkan file dukungan di lokasi kustom kotak centang dan menentukan lokasi khusus. Folder virtual akan tetap berada dalam project saat ini di Solution Explorer.

Membuat MSBuild memanggil Gradle untuk mem-build APK

MSBuild tidak dapat memanggil Gradle kecuali jika mengetahui lokasi project Gradle. Tetapkan lokasi ini menggunakan properti Direktori Build Gradle, seperti yang ditunjukkan dalam gambar 1.


Gambar 1. Properti Gradle Build Directory

Selain itu, tetapkan properti Application Module, Application Variant, dan APK Name (seperti yang ditunjukkan dalam gambar sebelumnya) agar MSBuild mengetahui hal yang harus di-build.

  • Application Module: Nama subproject Gradle. Ini adalah project utama yang ditetapkan dalam file settings.gradle. Ini biasanya disebut app untuk project yang langsung dibuat menggunakan Android Studio.
  • Application Variant: Varian Android yang akan di-build. Nilai ini harus ditetapkan sesuai konfigurasi MSBuild. Misalnya, build debug harus memiliki nilai yang ditetapkan ke varian debug. Jika nama konfigurasi MSBuild project Anda cocok dengan nama varian Gradle, cukup gunakan nilai default $(Configuration).
  • Nama APK: Nama file APK yang dihasilkan yang digunakan untuk proses debug dan pembuatan profil di komputer pengembangan. Nama ini diteruskan ke Gradle dan skrip build Gradle Anda harus mematuhinya (lihat MSBUILD_ANDROID_OUTPUT_APK_NAME properti di bagian berikut).

Mengubah skrip build Gradle

Selama proses build, MSBuild meneruskan informasi berikut sebagai properti project ke skrip Gradle. Ubah skrip build project yang ada (biasanya bernama build.gradle) untuk membaca properti ini.

  • MSBUILD_MIN_SDK_VERSION: Versi SDK minimum untuk mem-build APK. Tetapkan nilai ini di kotak Minimum Android SDK Version pada halaman properti project yang ditampilkan dalam gambar 2.


    Gambar 2. Properti Minimum Android SDK Version

    Skrip build Gradle harus menetapkan minSdkVersion ke nilai ini, sebagaimana ditunjukkan di bawah ini.

    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: Perkiraan nama APK yang di-build Gradle. Android Game Development Extension akan mencari APK yang cocok dengan nama ini, lalu men-deploy-nya ke perangkat yang terhubung (untuk proses debug dan pembuatan profil). Tetapkan nilai ini di kotak APK Name pada halaman properti project yang ditampilkan dalam gambar 3.


    Gambar 3. Properti APK Name

    Skrip build Gradle harus mematuhi properti ini. Misalnya, contoh berikut menetapkan nama APK output untuk semua varian ke nama yang dipilih oleh 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: Direktori yang berisi library bersama (file .so) yang dibuat oleh MSBuild. Tetapkan nilai ini di kotak Output Directory pada halaman properti project yang ditampilkan di bawah ini. Secara default, nilai ini adalah properti direktori output untuk project Visual Studio, sebagaimana ditunjukkan dalam gambar 4.


    Gambar 4. Properti Output Directory

    Gradle harus memaketkan file library bersama di folder ini di dalam APK agar aplikasi Android dapat memuatnya saat runtime.

    Groovy

    android {
  // ...

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

  // ...
}

    Kotlin

    android {
  // ...

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

  // ...
}

    Selain itu, karena setiap kode C/C++ kini dibuat oleh MSBuild, hapus bagian externalNativeBuild dalam skrip build Gradle Anda. Bagian ini digunakan dalam memanggil CMake atau ndk-build untuk mengompilasi kode C/C++, tetapi tidak lagi diperlukan.

  • MSBUILD_NDK_VERSION: Versi NDK yang akan digunakan untuk membuat project Anda. Tetapkan nilai ini di kotak Android NDK Version di halaman properti project yang ditampilkan dalam gambar 5.


    Gambar 5. Properti Android NDK Version

    Skrip build Gradle harus menetapkan ndkVersion ke nilai ini, seperti yang ditunjukkan:

    Groovy

    android {
  // ...

  ndkVersion MSBUILD_NDK_VERSION

  // ...
}

    Kotlin

    android {
  // ...

  ndkVersion = MSBUILD_NDK_VERSION

  // ...
}

    Untuk informasi selengkapnya, lihat topik Android Studio Menginstal dan mengonfigurasi NDK dan CMake.