Định cấu hình dự án

Định cấu hình dự án để sử dụng Android Game Development Extension.

Android Game Development Extension gọi MSBuild để xây dựng mã nguồn C/C++ thành các thư viện chia sẻ (.so) và thư viện tĩnh (.a). Trong quy trình xây dựng này, tác vụ MSBuild tuỳ chỉnh gọi Gradle để biên dịch mã nguồn Java và Kotlin, các tài sản gói và tạo một tệp APK cho hoạt động triển khai. Khi định cấu hình dự án, bạn phải đảm bảo rằng MSBuild có thông tin cần thiết để xây dựng cho nền tảng Android.

Xây dựng C/C++ bằng MSBuild

Một dự án Android điển hình được xây dựng bằng Gradle, trong đó mã gốc bên trong dự án được xây dựng bằng một lượt truyền bằng Gradle chạy CMake hoặc ndk-build. Với Android Game Development Extension dành cho Visual Studio, quy trình xây dựng sẽ đảo ngược. Lúc này, MSBuild là điểm bắt đầu của quy trình xây dựng. Trước tiên, MSBuild xây dựng tất cả mã nguồn C/C++ cho các nền tảng Android mới, được cài đặt trên hệ thống dưới dạng một phần của tiện ích (ví dụ: "Android-x86_64"). Sau đó, MSBuild gọi Gradle để đóng gói các tệp thư viện chia sẻ có chứa logic C/C++ vào một APK.

Trước tiên, bạn cần nhân bản logic của bản dựng hiện có của dự án trong CMake hoặc ndk-build trong MSBuild. Đặt các nền tảng đích là:

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

Tất cả nền tảng này đều được Android Game Development Extension cung cấp.

Thêm một nền tảng Android

Mặc dù dự án mẫu Teapot bao gồm cả các nền tảng Android, nhưng bạn phải thêm thủ công một nền tảng Android vào một dự án hiện có. Để thêm nền tảng mới, hãy làm theo các bước sau trong Visual Studio:

  1. Chọn Build > Configuration Manager (Xây dựng > Trình quản lý cấu hình).
  2. Trong Active solution platform (Nền tảng giải pháp đang hoạt động), hãy chọn <New> (Mới).

  3. Nhập một trong các nội dung sau cho nền tảng mới:

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

  4. Trong hộp Copy settings from (Sao chép chế độ cài đặt từ), hãy chọn một nền tảng Android khác hiện có, hoặc chọn <Empty> (Trống) nếu bạn chưa có nền tảng Android nào. Hãy nhớ bật tính năng Create new project platforms (Tạo nền tảng mới cho dự án).

Thêm một mục APK Android

Chọn Add > New Item > Visual C++ > Android > Android APK (Thêm > Mục mới > Visual C++ > Android > APK Android) rồi nhấp vào Add (Thêm). Định cấu hình ứng dụng Android trên hộp thoại sau.

  • Application Name (Tên ứng dụng): Tên của ứng dụng Android mà con người có thể đọc được.
  • Application ID (Mã ứng dụng): Mã nhận dạng duy nhất cho ứng dụng Android của bạn.
  • Solution Explorer Location (Vị trí trình khám phá giải pháp): Vị trí của thư mục ảo chứa các tệp hỗ trợ đóng gói Android đã thêm. Theo mặc định, các tệp này cũng được đặt trong dự án ở một thư mục cùng tên. Bạn có thể tuỳ chỉnh vị trí bằng cách chọn hộp đánh dấu Put support files in a custom location (Đặt các tệp hỗ trợ vào một vị trí tuỳ chỉnh) rồi chỉ định một vị trí tuỳ chỉnh. Thư mục ảo vẫn sẽ nằm trong dự án hiện tại thuộc Solution Explorer (Trình khám phá giải pháp).

Cho MSBuild gọi Gradle để xây dựng một APK

MSBuild không thể gọi Gradle trừ khi biết rõ vị trí của dự án Gradle. Hãy đặt vị trí này bằng thuộc tính Gradle Build Directory (Thư mục bản dựng Gradle) như trong hình 1.


Hình 1. Thuộc tính Gradle Build Directory (Thư mục bản dựng Gradle)

Ngoài ra, hãy đặt các thuộc tính Application Module (Mô-đun ứng dụng), Application Variant (Biến thể ứng dụng) và APK Name (Tên APK) (như trong hình trước) để MSBuild biết cần phải xây dựng gì.

  • Mô-đun ứng dụng: Tên của dự án phụ Gradle. Đây là dự án chính được đặt trong tệp settings.gradle. Giá trị này thường là app cho các dự án được tạo trực tiếp bằng Android Studio.
  • Biến thể ứng dụng: Biến thể Android cần xây dựng. Giá trị này phải được đặt theo các cấu hình MSBuild. Ví dụ: giá trị của một bản dựng gỡ lỗi phải được đặt là biến thể gỡ lỗi. Nếu tên cấu hình MSBuild của dự án khớp với tên biến thể Gradle, thì bạn chỉ cần sử dụng giá trị mặc định là $(Configuration).
  • Tên APK: Tên của tệp APK đã tạo được dùng để gỡ lỗi và phân tích tài nguyên trên máy tính dùng để phát triển của bạn. Tên này được truyền đến Gradle và và tập lệnh bản dựng Gradle phải tuân theo thuộc tính này (xem thuộc tính MSBUILD_ANDROID_OUTPUT_APK_NAME trong phần sau).

Sửa đổi tập lệnh bản dựng Gradle

Trong quá trình xây dựng, MSBuild truyền các thông tin sau dưới dạng thuộc tính dự án đến tập lệnh Gradle. Hãy thay đổi các tập lệnh bản dựng hiện có trong dự án (thường có tên là build.gradle) để đọc các thuộc tính này.

  • MSBUILD_MIN_SDK_VERSION: Phiên bản SDK tối thiểu để xây dựng APK. Hãy đặt giá trị này trong hộp Minimum Android SDK Version (Phiên bản SDK Android tối thiểu) trên trang thuộc tính dự án như trong hình 2.


    Hình 2. Thuộc tính Minimum Android SDK Version (Phiên bản SDK Android tối thiểu)

    Tập lệnh bản dựng Gradle sẽ đặt minSdkVersion thành giá trị này như trong ví dụ bên dưới.

    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: Tên dự kiến của APK mà Gradle xây dựng. Android Game Development Extension sẽ tìm một APK khớp với tên này, sau đó triển khai APK này cho các thiết bị được kết nối (để gỡ lỗi và phân tích tài nguyên). Đặt giá trị này trong hộp APK Name (Tên APK) trên trang thuộc tính của dự án như trong hình 3.


    Hình 3. Thuộc tính APK Name (Tên APK)

    Tập lệnh bản dựng Gradle phải tuân thủ thuộc tính này. Ví dụ: ví dụ sau đặt tên APK đầu ra cho tất cả biến thể thành tên do MSBuild chọn.

    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: Thư mục chứa các thư viện dùng chung (các tệp .so) do MSBuild xây dựng. Hãy đặt giá trị này trong hộp Output Directory (Thư mục đầu ra) trên trang thuộc tính của dự án như hình bên dưới Theo mặc định, giá trị này là thuộc tính thư mục đầu ra của dự án Visual Studio như trong hình 4.


    Hình 4. Thuộc tính Output Directory (Thư mục đầu ra)

    Gradle phải đóng gói các tệp thư viện dùng chung trong thư mục này bên trong APK để ứng dụng Android tải các tệp đó trong thời gian chạy.

    Groovy

    android {
  // ...

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

  // ...
}

    Kotlin

    android {
  // ...

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

  // ...
}

    Ngoài ra, vì hiện giờ mọi mã C/C++ đều do MSBuild xây dựng, hãy xoá phần externalNativeBuild trong tập lệnh bản dựng Gradle của bạn. Các phần này vốn được dùng để gọi CMake hoặc ndk-build nhằm biên dịch mã C/C++, nhưng hiện không còn cần thiết nữa.

  • MSBUILD_NDK_VERSION: Phiên bản của NDK mà bạn có thể sử dụng để xây dựng dự án. Đặt giá trị này trong hộp Android NDK Version (Phiên bản Android NDK) trên trên trang thuộc tính dự án như trong hình 5.


    Hình 5. Thuộc tính Android NDK Version (Phiên bản Android NDK)

    Tập lệnh bản dựng Gradle phải đặt ndkVersion thành giá trị này như trong ví dụ bên dưới:

    Groovy

    android {
  // ...

  ndkVersion MSBUILD_NDK_VERSION

  // ...
}

    Kotlin

    android {
  // ...

  ndkVersion = MSBUILD_NDK_VERSION

  // ...
}

    Để biết thêm thông tin, hãy xem chủ đề Cài đặt và định cấu hình NDK và CMake trên Android Studio.