Cómo compilar tu app desde la línea de comandos

Proyecto de Android que utiliza la herramienta de línea de comandos del wrapper de Gradle

Puedes ejecutar todas las tareas de compilación disponibles para tu proyecto de Android mediante la herramienta de la línea de comandos del wrapper de Gradle. Está disponible como archivo por lotes para Windows (gradlew.bat) y como secuencia de comandos shell para Linux y Mac (gradlew.sh), y se puede acceder a ella desde la raíz de cada proyecto que crees con Android Studio.

Para ejecutar una tarea con el wrapper, usa uno de los siguientes comandos desde una ventana de Terminal (en Android Studio, selecciona Ver > Ventanas de herramienta > Terminal):

  • En Windows:
    gradlew task-name
  • En Mac o Linux:
    ./gradlew task-name

Para ver una lista de todas las tareas de compilación disponibles para tu proyecto, ejecuta tasks.

    gradlew tasks
    

En el resto de esta página, se describen los aspectos básicos para compilar y ejecutar tu app con el wrapper de Gradle. Para obtener más información sobre cómo configurar tu compilación de Android, consulta Cómo configurar tu compilación.

Si prefieres usar las herramientas de Android Studio en lugar de las herramientas de la línea de comandos, consulta Cómo compilar y ejecutar tu app.

Información sobre los tipos de compilación

De manera predeterminada, existen dos tipos de compilación disponibles para cada app de Android: uno para depurar tu app (compilación de depuración) y otro para publicar tu app a los usuarios (compilación de lanzamiento). El resultado de cada compilación debe firmarse con un certificado antes de poder implementar la app en un dispositivo. La compilación de depuración se firma automáticamente con una clave de depuración proporcionada por las herramientas del SDK (es poco segura y no puedes publicar este APK en Google Play Store) y la compilación de lanzamiento debe firmarse con tu propia clave privada.

Si deseas compilar tu app para el lanzamiento, es importante que también firmes tu app con la clave de firma adecuada. Sin embargo, si estás dando los primeros pasos, puedes ejecutar rápidamente tus apps en un emulador o un dispositivo conectado mediante la compilación de un APK de depuración.

También puedes definir un tipo de compilación personalizado en tu archivo build.gradle y configurar dicha compilación para firmarla como compilación de depuración al incluir debuggable true. Para obtener más información, consulta Cómo configurar variantes de compilación.

Compilar e implementa un APK

Si bien la creación de un paquete de aplicación es la mejor manera de empaquetar tu app y cargarla en Play Console, la creación de un APK resulta más adecuada cuando deseas probar rápidamente una compilación de depuración o compartir tu app como artefacto implementable con otros.

Cómo compilar un APK de depuración

Para probar y depurar apps de forma inmediata, puedes crear un APK de depuración. El APK de depuración se firma con una clave de depuración proporcionada por las herramientas del SDK y permite la depuración mediante adb.

Para compilar un APK de depuración, abre una línea de comandos y navega hasta la raíz del directorio de tu proyecto. Para iniciar una compilación de depuración, invoca la tarea assembleDebug.

    gradlew assembleDebug
    

De esta forma, se creará un APK con el nombre module_name-debug.apk en project_name/module_name/build/outputs/apk/. El archivo ya está firmado con la clave de depuración y alineado con zipalign, por lo que puedes instalarlo de inmediato en un dispositivo.

Si deseas compilar el APK e instalarlo inmediatamente en un dispositivo conectado o un emulador en ejecución, invoca installDebug.

gradlew installDebug

La parte "Debug" de los nombres de tareas anteriores es solo una versión del nombre de la variante de compilación según la convención de mayúsculas y minúsculas, por lo que se puede reemplazar por cualquier variante de compilación que desees instalar. Por ejemplo, si tienes un tipo de producto de "demostración", puedes compilar la versión de depuración con la tarea assembleDemoDebug.

Para ver las tareas de instalación y compilación disponibles para cada variante (incluidas las tareas de desinstalación), ejecuta la tarea tasks.

Además, consulta la sección sobre cómo ejecutar tu app en el emulador y en un dispositivo.

Compila un APK de lanzamiento

Cuando esté todo listo para lanzar y distribuir tu app, debes compilar un APK de lanzamiento firmado con tu clave privada. Para obtener más información, ve a la sección sobre cómo firmar tu app desde la línea de comandos.

Cómo implementar tu app en el emulador

Para usar el emulador de Android, debes crear un dispositivo virtual Android (AVD) con Android Studio.

Una vez que cuentes con un AVD, inicia el emulador de Android y, luego, instala la app como se describe a continuación.

  1. En una línea de comandos, navega hasta android_sdk/tools/ y, luego, inicia emulador mediante la especificación de tu AVD:

    emulator -avd avd_name

    Si no estás seguro del nombre de AVD, ejecuta emulator -list-avds.

  2. Ahora puedes instalar tu app mediante una de las tareas de instalación de Gradle mencionadas en la sección sobre cómo compilar un APK de depuración o la herramienta adb.

    Si el APK se compila con un SDK de vista previa para desarrolladores (si targetSdkVersion es una letra en lugar de un número), debes incluir la opción -t con el comando install del sistema para instalar un APK de prueba.

        adb install path/to/your_app.apk
        

    Todos los APK que compilas se guardan en project_name/module_name/build/outputs/apk/.

Para obtener más información, consulta Cómo ejecutar apps en el emulador de Android.

Cómo implementar tu app en un dispositivo físico

Para poder ejecutar tu app en un dispositivo, debes habilitar la depuración USB en él. Puedes encontrar la opción en Configuración > Opciones para desarrolladores.

Nota: En Android 4.2 y versiones posteriores, la opción Opciones para desarrolladores está oculta de manera predeterminada. Para que esté disponible, ve a Configuración > Acerca del dispositivo y presiona Número de compilación siete veces. Cuando regreses a la pantalla anterior, verás Opciones para desarrolladores.

Una vez que tu dispositivo esté configurado y conectado mediante USB, puedes instalar tu app mediante las tareas de instalación de Gradle mencionadas en la sección acerca de cómo compilar un APK de depuración o la herramienta adb.

    adb -d install path/to/your_app.apk
    

Todos los APK que compilas se guardan en project_name/module_name/build/outputs/apk/.

Para obtener más información, consulta Cómo ejecutar apps en un dispositivo de hardware.

Cómo compilar un paquete de aplicación

Los paquetes Android App Bundle incluyen todos los recursos y códigos compilados de tu app, pero difieren en la generación de APK y la firma en Google Play. A diferencia de un APK, no puedes implementar un paquete de aplicación directamente en un dispositivo. Por lo tanto, si quieres probar o compartir de manera rápida un APK con otra persona, deberías compilar un APK.

La forma más fácil de crear un paquete de aplicación es mediante Android Studio. Sin embargo, si necesitas compilar un paquete de aplicación desde la línea de comandos, puedes hacerlo con Gradle o bundletool, como se describe en las siguientes secciones.

Cómo compilar un paquete de aplicación con Gradle

Si prefieres generar un paquete de aplicación desde la línea de comandos, ejecuta la tarea de Gradle bundleVariant en el módulo base de tu app. Por ejemplo, el siguiente comando compila un paquete de aplicación para la versión de depuración del módulo base:

./gradlew :base:bundleDebug
    

Si deseas compilar un paquete firmado para cargarlo en Play Console, primero debes configurar el archivo build.gradle del módulo base con la información de firma de tu app. Para obtener más información, ve a la sección sobre cómo configurar Gradle para firmar tu app. Por ejemplo, puedes compilar la versión de lanzamiento de tu app, y Gradle genera automáticamente un paquete de aplicación y lo firma con la información de firma que proporcionas en el archivo build.gradle.

Si, en cambio, deseas firmar un paquete de aplicación como un paso separado, puedes usar jarsigner para firmar tu paquete de aplicación desde la línea de comandos.

Cómo crear un paquete de aplicación con bundletool

bundletool es una herramienta de línea de comandos que Android Studio, el complemento de Gradle para Android y Google Play usan para convertir los recursos y el código compilado de tu app en paquetes de aplicación, y generar APK implementables con esos paquetes.

Por lo tanto, si bien es útil probar los paquetes de aplicación con bundletool y recrear localmente cómo Google Play genera archivos APK, por lo general, no necesitarás invocar bundletool para compilar el paquete de aplicación en sí, sino que deberías usar las tareas de Android Studio o Gradle, como se describe en las secciones anteriores.

Sin embargo, si no quieres usar las tareas de Android Studio o Gradle para crear paquetes, por ejemplo, si usas una cadena de herramientas de compilación personalizada, puedes usar bundletool desde la línea de comandos para crear un paquete de aplicación a partir de código y recursos compilados previamente. Si todavía no lo hiciste, descarga bundletool desde el repositorio de GitHub.

En esta sección, se describe cómo empaquetar los recursos y los códigos compilados de tu app y cómo usar bundletool desde la línea de comandos para convertirlos en Android App Bundle.

Cómo generar el manifiesto y los recursos en formato proto

bundletool requiere cierta información sobre el proyecto de tu app, como el manifiesto de la app y los recursos, para estar en el formato de búfer de protocolo de Google, también conocido como "protobuf", y usa la extensión de archivo *.pb. Los protobufs proporcionan un mecanismo extensible y neutral en cuanto al lenguaje y plataforma, para la serialización de datos estructurados; es similar a XML, pero más pequeño, más rápido y más simple.

Cómo descargar AAPT2

Puede generar el archivo de manifiesto y la tabla de recursos de tu app en formato protobuf con la última versión de AAPT2 del repositorio Maven de Google.

Para descargar AAPT2 desde el repositorio Maven de Google, haz lo siguiente:

  1. Ve a com.android.tools.build > aapt2 del índice del repositorio.
  2. Copia el nombre de la versión más reciente de AAPT2.
  3. Inserta el nombre de la versión que copiaste en la siguiente URL y especifica el sistema operativo de destino: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

    Por ejemplo, si quieres descargar la versión 3.2.0-alpha18-4804415 para Windows, debes usar https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

  4. Desde un navegador, accede a la URL; AAPT2 debería comenzar a descargarse rápidamente.

  5. Extrae el archivo JAR que acabas de descargar.

Usa AAPT2 para compilar los recursos de tu app con el siguiente comando:

    aapt2 compile \
    project_root/module_root/src/main/res/drawable/Image1.png \
    project_root/module_root/src/main/res/drawable/Image2.png \
    -o compiled_resources/
    

Durante la fase de vínculo, en la que AAPT2 vincula los diferentes recursos compilados en un solo APK, pídele a AAPT2 que convierta el manifiesto y los recursos compilados de tu app a formato protobuf. Para ello, incluye el indicador --proto-format de la siguiente manera:

    aapt2 link --proto-format -o output.apk \
    -I android_sdk/platforms/android_version/android.jar \
    --manifest project_root/module_root/src/main/AndroidManifest.xml \
    -R compiled_resources/*.flat \
    --auto-add-overlay
    

Luego, puedes extraer contenido del archivo APK de salida, como AndroidManifest.xml, resources.pb y otros archivos de recursos de tu app, ahora en formato protobuf. Necesitarás estos archivos cuando prepares el bundletool de entrada para compilar tu paquete de aplicación, como se describe en la siguiente sección.

Cómo empaquetar los recursos y los códigos compilados previamente

Antes de usar bundletool a fin de generar un paquete de aplicación para tu app, primero debes proporcionar archivos ZIP que contengan los recursos y los códigos compilados para un módulo de app determinado. El contenido y la organización del archivo ZIP de cada módulo son muy similares al del formato de Android App Bundle. Por ejemplo, debes crear un archivo base.zip para el módulo base de tu app y organizar su contenido de la siguiente manera:

Archivo o directorio Descripción
manifest/AndroidManifest.xml Es el manifiesto del módulo en formato protobuf.
dex/... Es un directorio con uno o más archivos DEX compilados de tu app. Estos archivos deben nombrarse de la siguiente manera: classes.dex, classes2.dex, classes3.dex, etcétera.
res/... Contiene los recursos del módulo en formato protobuf para todas las configuraciones de dispositivos. Los subdirectorios y los archivos deben organizarse de manera similar a la de un APK típico.
root/..., assets/... y lib/... Estos directorios son idénticos a los descritos en la sección sobre el formato de Android App Bundle.
resources.pb Es la tabla de recursos de tu app en formato protobuf.

Después de preparar el archivo ZIP para cada módulo de tu app, puedes pasarlos a bundletool con el fin de compilar tu paquete de aplicación, como se describe en la siguiente sección.

Cómo compilar tu paquete de aplicación con bundletool

Para crear tu paquete de aplicación, usa el comando bundletool build-bundle como se muestra a continuación:

    bundletool build-bundle --modules=base.zip --output=mybundle.aab
    

En la siguiente tabla, se describen en detalle los indicadores para el comando build-bundle:

Indicador Descripción
--modules=path-to-base.zip, path-to-module2.zip,path-to-module3.zip Especifica la lista de archivos ZIP del módulo que bundletool debe usar para compilar tu paquete de aplicación.
--output=path-to-output.aab Especifica la ruta y el nombre de archivo para el archivo de salida *.aab.
--config=path-to-BundleConfig.json Especifica la ruta a un archivo de configuración opcional que puedes usar para personalizar el proceso de compilación. Para obtener más información, consulta la sección sobre la personalización de la generación de APK en sentido descendente.
--metadata-file=target-bundle-path:local-file-path Pídele a bundletool que empaquete un archivo de metadatos opcional en tu paquete de aplicación. Puedes usar este archivo para incluir datos, como las asignaciones de ProGuard o la lista completa de los archivos DEX de tu app, que pueden ser útiles para otros pasos en tu cadena de herramientas o en una tienda de aplicaciones.

target-bundle-path especifica una ruta relativa a la raíz del paquete de la aplicación donde te gustaría que se empaquetara el archivo de metadatos, y local-file-path especifica la ruta al propio archivo de metadatos.

Cómo personalizar la generación de APK en sentido descendente

Los paquetes de aplicación incluyen un archivo BundleConfig.pb que proporciona metadatos que las tiendas de aplicaciones, como Google Play, requieren al generar archivos APK desde el paquete. Si bien bundletool crea este archivo por ti, puedes configurar algunos aspectos de los metadatos en un archivo BundleConfig.json y transferirlo al comando bundletool build-bundle, bundletool luego convierte y combina este archivo con la versión de protobuf incluida en cada paquete de aplicación.

Por ejemplo, puedes controlar qué APK de categorías de configuración habilitar o inhabilitar. El siguiente ejemplo de un archivo BundleConfig.json inhabilita los APK de configuración que tienen como destino un idioma diferente (es decir, los recursos para todos los idiomas se incluyen en sus respectivos APK de funciones dinámicas o básicas):

{
      "optimizations": {
        "splitsConfig": {
          "splitDimension": [{
            "value": "LANGUAGE",
            "negate": true
          }]
        }
      }
    }
    

En tu archivo BundleConfig.json, también puedes especificar qué tipos de archivos dejar sin comprimir al empaquetar APK mediante patrones globales, de la siguiente manera:

{
      "compression": {
        "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
      }
    }
    

Ten en cuenta que, de manera predeterminada, bundletool no comprime las bibliotecas nativas de tu app (en Android 6.0 o versiones posteriores) y la tabla de recursos (resources.arsc). Para obtener una descripción completa de lo que puedes configurar en tu BundleConfig.json, inspecciona el archivo bundletool config.proto, que se escribe con la sintaxis Proto3.

Implementa tu app desde un paquete de aplicación

Si creaste y firmaste un paquete de aplicación, usa bundletool para generar APK y, luego, implementarlos en un dispositivo.

Cómo firmar tu app desde la línea de comandos

No necesitas Android Studio para firmar tu app. Puedes hacerlo desde la línea de comandos mediante apksigner para APK o jarsigner para conjuntos de apps, o bien configurar Gradle para que se encargue de ello durante la compilación. De cualquier manera, primero debes generar una clave privada mediante keytool, de la siguiente manera:

    keytool -genkey -v -keystore my-release-key.jks
    -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias
    

En el ejemplo anterior, se te solicitan contraseñas para el keystore y la clave, y para otorgar los campos de nombre distintivo para tu clave. Luego, se genera el almacén de claves como un archivo llamado my-release-key.jks, que se guarda en el directorio actual (puedes moverlo cuando lo desees). El almacén de claves contiene una clave única válida por 10,000 días.

Ahora puedes firmar tu APK o paquete de aplicación de forma manual, o configurar Gradle para firmar tu aplicación durante el proceso de compilación, como se describe en las siguientes secciones.

Cómo firmar tu app manualmente desde la línea de comandos

Si quieres firmar un paquete de aplicación desde la línea de comandos, puedes usar jarsigner. Si, en su lugar, quieres firmar un APK, debes usar zipalign y apksigner como se describe a continuación.

  1. Abre una línea de comandos desde Android Studio, selecciona Ver > Ventanas de herramienta > Terminal y navega al directorio donde se encuentra el APK.
  2. Alinea el APK sin firmar con zipalign.

        zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
        

    zipalign garantiza que todos los datos descomprimidos comiencen con una alineación de bytes en particular relacionada con el comienzo del archivo, lo que reduce el consumo de memoria RAM de una app.

  3. Firma tu APK con tu clave privada mediante apksigner.

        apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
        

    En este ejemplo, se genera el APK firmado en my-app-release.apk una vez que se firma con una clave privada y un certificado, que se almacenan en un único archivo de almacén de claves: my-release-key.jks.

    La herramienta apksigner admite otras opciones de firmas, incluida la firma de un archivo APK con archivos de clave y certificado privados separados y la firma de un APK con varios firmantes. Para obtener información detallada, consulta la referencia de apksigner.

    Nota: Para usar la herramienta apksigner, debes tener instalada la revisión 24.0.3 o versiones posteriores de Android SDK Build Tools. Puedes actualizar este paquete con SDK Manager.

  4. Verifica que tu APK esté firmado.

        apksigner verify my-app-release.apk
        

Cómo configurar Gradle para firmar tu app

Abre el archivo build.gradle de nivel de módulo y agrega el bloque signingConfigs {} con entradas para storeFile, storePassword, keyAlias y keyPassword, y luego pasa ese objeto a la propiedad signingConfig en tu tipo de compilación. Por ejemplo:

android {
        ...
        defaultConfig { ... }
        signingConfigs {
            release {
                // You need to specify either an absolute path or include the
                // keystore file in the same directory as the build.gradle file.
                storeFile file("my-release-key.jks")
                storePassword "password"
                keyAlias "my-alias"
                keyPassword "password"
            }
        }
        buildTypes {
            release {
                signingConfig signingConfigs.release
                ...
            }
        }
    }
    

Ahora, cuando compiles tu app invocando una tarea de Gradle, Gradle firmará tu app (y ejecutará zipaling) por ti.

Ahora que ya configuraste la compilación de lanzamiento con tu clave de firma, la tarea "install" estará disponible para ese tipo de compilación. Por lo tanto, podrás compilar, alinear, firmar e instalar el APK de lanzamiento en un emulador o dispositivo con la tarea installRelease.

Un app firmada con tu clave privada está lista para su distribución, pero antes debes leer más información sobre cómo publicar tu app y revisar la lista de tareas de lanzamiento para Google Play.