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:
- Select Build > Configuration Manager.
- Under Active solution platform, select <New>.
Type one of the following for the new platform:
- Android-armeabi-v7a
- Android-arm64-v8a
- Android-x86
- Android-x86_64
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 calledapp
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 propertyThe 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 propertyThe 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 propertyGradle 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 propertyThe 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.