Đị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). Là một phần trong quy trình xây dựng, 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 để 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 hoạt động truyền trong 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. Bây giờ, MSBuild là điểm khởi đầu của quy trình xây dựng. Tất cả mã nguồn C/C++ đều được MSBuild xây dựng trước tiên 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 nên sao chép logic xây dựng hiện có của dự án trong CMake hoặc ndk-build trong MSBuild. Đặt các nền tảng mục tiêu như sau:

  • 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 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), 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ừ), chọn None (Không). Hãy nhớ bật tính năng Create new project platforms (Tạo nền tảng dự án mới).

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 dễ đọc của ứng dụng Android.
  • Application ID (ID ứ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 ở 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. Đặt vị trí này bằng cách sử dụng thuộc tính Gradle Build Directory (Thư mục bản dựng Gradle), như được hiển thị 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ư được hiển thị trong hình ảnh trước) để MSBuild biết những yếu tố cần xây dựng.

  • 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 gỡ lỗi phải 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 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à 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. Đặ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 hiển thị 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ư minh hoạ 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 giá trị này trong hộp APK Name (Tên APK) trên trang thuộc tính của dự án hiển thị 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 chia sẻ (tệp .so) do MSBuild xây dựng. Đặ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 hiển thị 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 nên đóng gói các tệp thư viện chia sẻ 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 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 trang thuộc tính dự án hiển thị 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ư được minh hoạ:

    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.