Configurer un projet

Configurez un projet pour utiliser l'extension Android Game Development.

L'extension Android Game Development appelle MSBuild pour compiler le code source C/C++ dans des bibliothèques partagées (.so) et statiques (.a). Dans le cadre du processus de compilation, une tâche MSBuild personnalisée appelle Gradle pour compiler le code source Java et Kotlin, empaqueter les éléments et générer un fichier APK pour le déploiement. Lorsque vous configurez votre projet, vous devez vous assurer que MSBuild dispose des informations nécessaires pour la plate-forme Android.

Compiler C/C++ avec MSBuild

Un projet Android classique est conçu à l'aide de Gradle, où le code natif dans le projet est compilé par un passage Gradle qui exécute CMake ou ndk-build. Avec l'extension Android Game Development pour Visual Studio, le processus de compilation est inversé. MSBuild est maintenant le point de départ du processus de compilation. Tout le code source C/C++ est d'abord créé par MSBuild pour les nouvelles plates-formes Android installées sur votre système dans le cadre de l'extension (par exemple, "Android-x86_64"). MSBuild appelle ensuite Gradle pour empaqueter les fichiers de bibliothèque partagée contenant le logique C/C++ dans un fichier APK.

Vous devez d'abord répliquer la logique de compilation existante de votre projet dans CMake ou ndk-build dans MSBuild. Définissez les plates-formes cibles comme suit :

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

Ces plates-formes sont toutes fournies par l'extension Android Game Development.

Ajouter une plate-forme Android

Bien que l'exemple de projet Teapot comprenne des plates-formes Android, vous devez ajouter manuellement une plate-forme Android à un projet existant. Pour ce faire, procédez comme suit dans Visual Studio :

  1. Sélectionnez Build > Configuration Manager (Compiler > Gestionnaire de configuration).
  2. Sous Active solution platform, sélectionnez New (Plate-forme de solution active > Nouvelle).

  3. Saisissez l'une des architectures suivantes pour la nouvelle plate-forme :

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

  4. Dans le champ Copy settings from (Copier les paramètres de), sélectionnez une autre plate-forme Android ou <Empty> (Vide) si vous n'avez pas encore de plate-forme Android. Assurez-vous d'avoir activé l'option Create new project platforms (Créer des plates-formes de projet).

Ajouter un élément APK Android

Sélectionnez Add > New Item > Visual C++ > Android > Android APK (Ajouter > Nouvel élément > Visual C++ > Android > APK Android), puis cliquez sur Add (ajouter). Configurez l'application Android dans la boîte de dialogue suivante.

  • Application Name : nom de votre application sous forme lisible.
  • Application ID : identifiant unique de votre application Android.
  • Solution Explorer Location : emplacement du dossier virtuel contenant les fichiers de prise en charge de package Android ajoutés. Par défaut, ces fichiers sont également situés dans le projet, dans un dossier portant le même nom. Pour personnaliser l'emplacement, cochez la case Put support files in a custom location (Placer les fichiers sous-jacents dans un emplacement personnalisé), puis spécifiez l'emplacement de votre choix. Le dossier virtuel se trouve toujours sous le projet actuel dans l'explorateur de solutions.

S'assurer que MSBuild appelle Gradle pour créer un APK

MSBuild ne peut pas appeler Gradle à moins de connaître l'emplacement du projet Gradle. Définissez cet emplacement à l'aide de la propriété Répertoire de compilation Gradle, comme illustré dans la figure 1.


Figure 1. Propriété Gradle Build Directory (répertoire de compilation Gradle)

Définissez également les propriétés Application Module (module d'application), Application Variant (variante de l'application) et APK Name (nom de l'APK), comme illustré dans l'image précédente, pour que MSBuild sache quoi compiler.

  • Application Module : nom du sous-projet Gradle. Il s'agit du projet principal défini dans le fichier settings.gradle. Il est généralement appelé app pour les projets créés directement à l'aide d'Android Studio.
  • Application Variant : il s'agit de la variante Android à créer. Cette valeur doit être définie en fonction des configurations MSBuild. Par exemple, une version de débogage doit avoir une valeur définie sur la variante de débogage. Si le nom de la configuration MSBuild de votre projet correspond aux noms des variantes Gradle, utilisez simplement la valeur par défaut $(Configuration).
  • APK Name : nom du fichier APK généré qui sera utilisé pour le débogage et le profilage sur l'ordinateur de développement. Ce nom est transmis à Gradle et doit être respecté par le script de compilation Gradle (consultez la propriété MSBUILD_ANDROID_OUTPUT_APK_NAME dans la section suivante).

Modifier vos scripts de compilation Gradle

Lors de la compilation, MSBuild transmet les informations suivantes en tant que propriétés de projet au script Gradle. Modifiez les scripts de compilation existants de votre projet (généralement nommé build.gradle) pour lire ces propriétés.

  • MSBUILD_MIN_SDK_VERSION : version minimale du SDK permettant de créer l'APK. Définissez cette valeur dans le champ Minimum Android SDK Version (version minimale du SDK Android) sur la page des propriétés du projet illustrée dans la figure 2.


    Figure 2. Propriété Minimum Android SDK Version (version minimale Android)

    Le script de compilation Gradle doit définir minSdkVersion sur cette valeur, comme indiqué ci-dessous.

    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 : nom attendu de l'APK créé par Gradle. L'extension Android Game Development recherche un APK correspondant à ce nom, puis le déploie sur les appareils connectés (à des fins de débogage et de profilage). Définissez cette valeur dans le champ APK Name sur la page des propriétés du projet illustrée à la figure 3.


    Figure 3. Propriété APK Name

    Le script de compilation Gradle doit respecter cette propriété. Par exemple, l'exemple suivant définit le nom de l'APK de sortie pour toutes les variantes sur le nom choisi par 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 : répertoire contenant les bibliothèques partagées (fichiers .so) créées par MSBuild. Définissez cette valeur dans le champ Output Directory (répertoire de sortie) de la page des propriétés du projet illustrée ci-dessous. Par défaut, cette valeur correspond à la propriété de répertoire de sortie du projet Visual Studio, comme illustré dans la figure 4.


    Figure 4. Propriété Output Directory

    Gradle doit empaqueter les fichiers de bibliothèque partagée de ce dossier dans l'APK afin que l'application Android puisse les charger au moment de l'exécution.

    Groovy

    android {
  // ...

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

  // ...
}

    Kotlin

    android {
  // ...

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

  // ...
}

    De plus, comme le code C/C++ est désormais créé par MSBuild, supprimez les sections externalNativeBuild de vos scripts de compilation Gradle. Ces sections étaient utilisées pour appeler CMake ou ndk-build afin de compiler le code C/C++, mais elles ne sont plus nécessaires.

  • MSBUILD_NDK_VERSION : version du NDK à utiliser pour compiler votre projet. Définissez cette valeur dans le champ Android NDK Version (version du NDK Android) sur la page des propriétés du projet illustrée à la figure 5.


    Figure 5. Propriété Android NDK Version

    Le script de compilation Gradle doit définir ndkVersion sur cette valeur, comme indiqué ci-dessous :

    Groovy

    android {
  // ...

  ndkVersion MSBUILD_NDK_VERSION

  // ...
}

    Kotlin

    android {
  // ...

  ndkVersion = MSBUILD_NDK_VERSION

  // ...
}

    Pour en savoir plus, consultez la rubrique Installer et configurer le NDK et CMake d'Android Studio.