配置项目

配置项目以使用 Android 游戏开发扩展。

Android 游戏开发扩展调用 MSBuild 将 C/C++ 源代码构建成共享库 (.so) 和静态库 (.a)。作为构建过程的一部分，自定义 MSBuild 任务调用 Gradle 来编译 Java 和 Kotlin 源代码、打包资源并生成用于部署的 APK 文件。配置项目时，必须确保 MSBuild 拥有构建 Android 平台所需的信息。

使用 MSBuild 构建 C/C++

典型的 Android 项目是使用 Gradle 构建的，其中项目内部的原生代码由运行 CMake 或 ndk-build 的 Gradle 传递构建。使用 Visual Studio 的 Android 游戏开发扩展，构建过程被反转。现在 MSBuild 是构建过程的起点。所有 C/C++ 源代码首先由 MSBuild 构建，用于作为扩展一部分安装在系统上的新 Android 平台（例如，“Android-x86_64”）。然后，MSBuild 调用 Gradle 将包含 C/C++ 逻辑的共享库文件打包到 APK 中。

您应该首先在 MSBuild 中复制项目现有的构建逻辑到 CMake 或 ndk-build 中。将目标平台设置为以下平台

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

这些平台均由 Android 游戏开发扩展提供。

添加 Android 平台

虽然茶壶示例项目包含 Android 平台，但您必须手动将 Android 平台添加到现有项目中。要添加新平台，请在 Visual Studio 中执行以下操作

  1. 选择生成 > 配置管理器。
  2. 在活动解决方案平台下，选择<新建>。

  3. 为新平台键入以下内容之一

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

  4. 在从复制设置框中，选择另一个现有的 Android 平台，或者如果您还没有任何 Android 平台，则选择<空>。确保已启用创建新的项目平台。

添加 Android APK 项

选择添加 > 新建项 > Visual C++ > Android > Android APK，然后单击添加。在以下对话框中配置 Android 应用程序。

  • 应用程序名称：Android 应用程序的可读名称。
  • 应用程序 ID：Android 应用程序的唯一标识符。
  • 解决方案资源管理器位置：包含添加的 Android 打包支持文件的虚拟文件夹的位置。默认情况下，这些文件也位于项目中，位于具有相同名称的文件夹中。您可以通过选中将支持文件放在自定义位置复选框并指定自定义位置来自定义位置。虚拟文件夹仍将在解决方案资源管理器中的当前项目下。

使 MSBuild 调用 Gradle 构建 APK

除非 MSBuild 知道 Gradle 项目的位置，否则它无法调用 Gradle。使用Gradle 构建目录属性设置此位置，如图 1 所示。


图 1. Gradle 构建目录属性

此外，设置应用程序模块、应用程序变体和APK 名称属性（如上图所示），以便 MSBuild 知道要构建什么。

  • 应用程序模块：Gradle 子项目的名称。这是在 settings.gradle 文件中设置的主项目。对于使用 Android Studio 直接创建的项目，它通常称为 app。
  • 应用程序变体：要构建的 Android 变体。应根据 MSBuild 配置设置此值。例如，调试构建应将值设置为调试变体。如果项目的 MSBuild 配置名称与 Gradle 变体名称匹配，则只需使用 $(Configuration) 的默认值。
  • APK 名称：生成的 APK 文件的名称，用于在开发计算机上进行调试和分析。此名称传递给 Gradle，并且 Gradle 构建脚本应尊重此名称（请参阅以下部分中的属性 MSBUILD_ANDROID_OUTPUT_APK_NAME）。

修改 Gradle 构建脚本

在构建期间，MSBuild 将以下信息作为项目属性传递给 Gradle 脚本。更改项目的现有构建脚本（通常命名为 build.gradle）以读取这些属性。

  • MSBUILD_MIN_SDK_VERSION：构建 APK 的最低 SDK 版本。在图 2 中显示的项目属性页上的最低 Android SDK 版本框中设置此值。


    图 2. 最低 Android SDK 版本属性

    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：Gradle 构建的 APK 的预期名称。Android 游戏开发扩展将查找与该名称匹配的 APK，然后将其部署到连接的设备（用于调试和分析）。在图 3 中显示的项目属性页上的APK 名称框中设置此值。


    图 3. APK 名称属性

    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：包含 MSBuild 构建的共享库 (.so 文件) 的目录。在下面显示的项目属性页上的输出目录框中设置此值。默认情况下，此值为 Visual Studio 项目的输出目录属性，如图 4 所示。


    图 4. 输出目录属性

    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 构建，因此请删除 Gradle 构建脚本中的 externalNativeBuild 部分。这些部分用于调用 CMake 或 ndk-build 来编译 C/C++ 代码，但现在不再需要。

  • MSBUILD_NDK_VERSION：用于构建项目的 NDK 版本。在图 5 中显示的项目属性页上的Android NDK 版本框中设置此值。


    图 5. Android NDK 版本属性

    Gradle 构建脚本应将 ndkVersion 设置为此值，如下所示

    Groovy

    android {
  // ...

  ndkVersion MSBUILD_NDK_VERSION

  // ...
}

    Kotlin

    android {
  // ...

  ndkVersion = MSBUILD_NDK_VERSION

  // ...
}

    有关更多信息，请参阅 Android Studio 主题安装和配置 NDK 和 CMake。