Configure a project

Configure a project to use the Android Game Development Extension.

The Android Game Development Extension invokes MSBuild to build C/C++ source code into shared libraries (.so) and static libraries (.a). As part of the build process, a custom MSBuild task invokes Gradle to compile Java and Kotlin source code, package assets, and generate an APK file for deployment. When you configure your project, you must ensure that MSBuild has the information it needs to build for the Android platform.

Build C/C++ with MSBuild

A typical Android project is built with Gradle, where the native code inside the project is built by a Gradle pass that runs either CMake or ndk-build. With the Android Game Development Extension for Visual Studio, the build process is inverted. Now MSBuild is the starting point of the build process. All C/C++ source code is built first by MSBuild for the new Android platforms installed on your system as part of the extension (for example, "Android-x86_64"). MSBuild then invokes Gradle to package the shared library files that contain your C/C++ logic into an APK.

You should first replicate your project's existing build logic in CMake or ndk-build in MSBuild. Set the target platforms to the following:

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

These platforms are all provided by the Android Game Development Extension.

Add an Android Platform

While the teapot sample project includes Android platforms, you must manually add an Android platform to an existing project. To add a new platform, do the following in Visual Studio:

  1. Select Build > Configuration Manager.
  2. Under Active solution platform, select <New>.

  3. Type one of the following for the new platform:

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

  4. In the Copy settings from box, select another existing Android platform, or <Empty> if you do not have any Android platforms yet. Make sure you enabled Create new project platforms.

Add an Android APK item

Select Add > New Item > Visual C++ > Android > Android APK and click Add. Configure the Android application on the following dialog.

  • Application Name: The human-readable name of your Android application.
  • Application ID: The unique identifier for your Android application.
  • Solution Explorer Location: Location of the virtual folder that contains the added Android packaging support files. By default, these files are also located in the project in a folder with the same name. You can customize the location by selecting the Put support files in a custom location checkbox and specifying a custom location. The virtual folder will still be under the current project in the Solution Explorer.

Make MSBuild invoke Gradle to build an APK

MSBuild cannot invoke Gradle unless it knows the location of the Gradle project. Set this location using the Gradle Build Directory property, as shown in figure 1.


Figure 1. Gradle Build Directory property

In addition, set the Application Module, Application Variant, and APK Name properties (as shown in the previous image) in order for MSBuild to know what to build.

  • Application Module: The name of the Gradle subproject. This is the main project set in the settings.gradle file. It is usually called app for projects directly created using Android Studio.
  • Application Variant: The Android variant to build. This value should be set according to the MSBuild configurations. For example, a debug build should have a value set to the debug variant. If your project's MSBuild configuration name matches the Gradle variant names, then just use the default value of $(Configuration).
  • APK Name: The name of the generated APK file used for debugging and profiling on your development computer. This name is passed to Gradle and your Gradle build script should respect this (see the property MSBUILD_ANDROID_OUTPUT_APK_NAME in the following section).

Modify your Gradle build scripts

During the build, MSBuild passes the following information as project properties to the Gradle script. Change your project's existing build scripts (typically named build.gradle) to read these properties.

  • MSBUILD_MIN_SDK_VERSION: The minimum SDK version for building the APK. Set this value in the Minimum Android SDK Version box on the project property page shown in figure 2.


    Figure 2. Minimum Android SDK Version property

    The Gradle build script should set minSdkVersion to this value, as shown below.

    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: The expected name of the APK that Gradle builds. The Android Game Development Extension will look for an APK matching this name and then deploy it to connected devices (for debugging and profiling). Set this value in the APK Name box on the project property page shown in figure 3.


    Figure 3. APK Name property

    The Gradle build script must respect this property. For example, the following example sets the output APK name for all variants to the name chosen by 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: The directory containing the shared libraries (.so files) built by MSBuild. Set this value in the Output Directory box on the project property page shown below. By default, this value is the output directory property for the Visual Studio project, as shown in figure 4.


    Figure 4. Output Directory property

    Gradle should package the shared library files in this folder inside the APK in order for the Android application to load them at runtime.

    Groovy

    android {
  // ...

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

  // ...
}

    Kotlin

    android {
  // ...

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

  // ...
}

    In addition, since any C/C++ code is now built by MSBuild, remove the externalNativeBuild sections in your Gradle build scripts. These sections were used to invoke CMake or ndk-build to compile your C/C++ code, but are no longer needed.

  • MSBUILD_NDK_VERSION: The version of the NDK to use to build your project. Set this value in the Android NDK Version box on the project property page shown in figure 5.


    Figure 5. Android NDK Version property

    The Gradle build script should set ndkVersion to this value, as shown:

    Groovy

    android {
  // ...

  ndkVersion MSBUILD_NDK_VERSION

  // ...
}

    Kotlin

    android {
  // ...

  ndkVersion = MSBUILD_NDK_VERSION

  // ...
}

    For more information, see the Android Studio topic Install and configure the NDK and CMake.