Cómo configurar un proyecto

Configura un proyecto de modo que use Android Game Development Extension.

Android Game Development Extension invoca a MSBuild para compilar código fuente C/C++ en bibliotecas compartidas (.so) y bibliotecas estáticas (.a). Como parte del proceso de compilación, una tarea personalizada de MSBuild invoca a Gradle a fin de compilar el código fuente de Java y Kotlin, elementos del paquete y generar un archivo APK para la implementación. Cuando configuras tu proyecto, debes asegurarte de que MSBuild tenga la información que necesita a fin de compilar para la plataforma de Android.

Cómo compilar C/C++ con MSBuild

Un proyecto típico de Android se compila con Gradle, en donde el código nativo dentro de este proyecto se compila a través de un pase de Gradle que ejecuta CMake o ndk-build. Con Android Game Development Extension para Visual Studio, se invierte el proceso de compilación. Ahora, MSBuild es el punto de partida del proceso de compilación. MSBuild compila todo el código fuente de C/C++ para las nuevas plataformas de Android instaladas en el sistema como parte de la extensión (por ejemplo, "Android-x86_64"). MSBuild invoca a Gradle para empaquetar los archivos de la biblioteca compartida que contienen la lógica C/C++ en el APK.

Primero, debes replicar la lógica de compilación existente de tu proyecto en CMake o ndk-build en MSBuild. Establece las siguientes plataformas de segmentación:

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

Android Game Development Extension brinda todas estas plataformas.

Cómo agregar una plataforma de Android

Si bien el proyecto de ejemplo de la tetera incluye plataformas de Android, debes agregar manualmente una plataforma de Android a un proyecto existente. Para agregar una plataforma nueva, haz lo siguiente en Visual Studio:

  1. Selecciona Compilar > Administrador de configuración.
  2. En Plataforma de soluciones activas, selecciona <New>.
  3. Escribe una de las siguientes opciones para la plataforma nueva:

    • Android-armeabi-v7a
    • Android-arm64-v8a
    • Android-x86
    • Android-x86_64
  4. En el cuadro Copiar configuración desde, selecciona otra plataforma de Android existente o haz clic en <Empty> si aún no tienes ninguna plataforma de Android. Asegúrate de habilitar Crear nuevas plataformas de proyecto.

Cómo agregar un elemento de APK de Android

Selecciona Add > New Item > Visual C++ > Android > Android APK y haz clic en Add. Configura la aplicación para Android en el siguiente diálogo.

  • Nombre de aplicación: Es el nombre legible de tu aplicación para Android.
  • Application ID: Es el identificador único de tu aplicación para Android.
  • Ubicación del explorador de soluciones: Es la ubicación de la carpeta virtual que contiene los archivos agregados de compatibilidad del empaquetado de Android. De forma predeterminada, estos archivos también se ubican en el proyecto, en una carpeta con el mismo nombre. Para personalizar la ubicación, selecciona la casilla de verificación Put support files in a custom location y especifica una ubicación personalizada. La carpeta virtual se ubicará en el proyecto actual, en el explorador de soluciones.

Cómo lograr que MSBuild invoque a Gradle para compilar un APK

MSBuild no puede invocar a Gradle, a menos que conozca la ubicación del proyecto de Gradle. Establece esta ubicación con la propiedad Gradle Build Directory, como se muestra en la Figura 1.


Figura 1: Propiedad Gradle Build Directory

Además, configura las propiedades Application Module, Application Variant y APK Name (como se muestra en la imagen anterior) para que MSBuild sepa qué compilar.

  • Application Module: Es el nombre del subproyecto de Gradle. Este es la configuración del proyecto principal en el archivo settings.gradle. Por lo general, llama a app para proyectos que se crearon directamente con Android Studio.
  • Application Variant: Es la variante de Android que se compilará. Este valor se debe establecer según las configuraciones de MSBuild. Por ejemplo, una compilación de depuración debe tener un valor establecido para la variante de depuración. Si el nombre de la configuración de MSBuild de tu proyecto coincide con los nombres de las variantes de Gradle, solo usa el valor predeterminado de $(Configuration).
  • APK Name: Es el nombre del archivo APK generado que se usa para depurar y generar perfiles en la computadora de desarrollo. Este nombre se pasa a Gradle, y tu secuencia de comandos de compilación de Gradle debe respetarlo (consulta la propiedad MSBUILD_ANDROID_OUTPUT_APK_NAME en la siguiente sección).

Cómo modificar las secuencias de comandos de compilación de Gradle

Durante la compilación, MSBuild pasa la siguiente información como propiedades del proyecto a la secuencia de comandos de Gradle. Cambia las secuencias de comandos de compilación existentes de tu proyecto (que, en general, se denominan build.gradle) para leer estas propiedades.

  • MSBUILD_MIN_SDK_VERSION: Es la versión mínima del SDK para compilar el APK. Configura este valor en el cuadro Minimum Android SDK Version de la página de propiedad del proyecto que se muestra en la Figura 2.


    Figura 2: Propiedad Minimum Android SDK Version

    La secuencia de comandos de compilación de Gradle debe establecer minSdkVersion en este valor, como se muestra a continuación.

    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: Es el nombre previsto del APK que compila Gradle. Android Game Development Extension buscará un APK que coincida con este nombre y, luego, lo implementará en los dispositivos conectados (para depurar y generar perfiles). Establece este valor en el cuadro APK Name de la página de propiedad del proyecto que se muestra en la Figura 3.


    Figura 3: Propiedad APK Name

    La secuencia de comandos de compilación de Gradle debe respetar esta propiedad. En el siguiente ejemplo, se establece el nombre del APK de salida para todas las variantes del nombre que eligió 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: Es el directorio que contiene las bibliotecas compartidas (archivos .so) que compiló MSBuild. Establece este valor en el cuadro Output Directory en la página de propiedades del proyecto que se muestra a continuación. De forma predeterminada, este valor es la propiedad del directorio de salida para el proyecto de Visual Studio, como se muestra en la Figura 4.


    Figura 4: Propiedad Output Directory

    Gradle debe empaquetar los archivos de la biblioteca compartida en esta carpeta dentro del APK, de modo que la aplicación para Android los cargue en el tiempo de ejecución.

    Groovy

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

    Kotlin

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

    Además, como MSBuild ahora compila cualquier código C/C++, quita las secciones externalNativeBuild de las secuencias de comandos de compilación de Gradle. Estas secciones se usaban para invocar a CMake o ndk-build a fin de compilar tu código C o C++, pero ya no son necesarios.

  • MSBUILD_NDK_VERSION: Es la versión del NDK que se usará para compilar tu proyecto. Establece este valor en el cuadro Android NDK Version de la página de propiedad del proyecto que se muestra en la Figura 5.


    Figura 5: Propiedad Android NDK Version

    La secuencia de comandos de compilación de Gradle debe establecer ndkVersion en este valor, como se muestra a continuación.

    Groovy

    android {
      // ...
    
      ndkVersion MSBUILD_NDK_VERSION
    
      // ...
    }
    

    Kotlin

    android {
      // ...
    
      ndkVersion = MSBUILD_NDK_VERSION
    
      // ...
    }
    

    Para obtener más información, consulta el tema sobre Android Studio Cómo instalar y configurar el NDK y CMake.