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

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 Terminal (en Android Studio, selecciona View > Tool Windows > Terminal):

• En la Shell de comandos de Windows:

  gradlew task-name

• En Mac, Linux o Windows PowerShell, haz lo siguiente:

  ./gradlew task-name

A fin de 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 a fin de depurar tu app (compilación de depuración) y otro con el objetivo de 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 que proporcionan 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 la firmes 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 el archivo build.gradle.kts y configurar esa compilación para firmarla como compilación de depuración incluyendo debuggable true. Para obtener más información, consulta el artículo Cómo configurar variantes de compilación.

Cómo compilar e implementar un APK

Si bien crear un paquete de aplicación es la mejor manera de empaquetar tu app y subirla a Play Console, crear un APK es más adecuado 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 la app de forma inmediata, puedes compilar un APK de depuración. El APK se firma con una clave de depuración proporcionada por las herramientas del SDK y permite realizar 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 el directorio 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 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 una variante de producto de "demostración", puedes compilar la versión de depuración con la tarea assembleDemoDebug.

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

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

Cómo compilar un paquete de lanzamiento o un APK

Cuando tengas todo listo para lanzar y distribuir tu app, deberás compilar un APK o paquete 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 Android Emulator, debes crear un dispositivo virtual Android (AVD) con Android Studio.

Una vez que cuentes con un AVD, inicia Android Emulator e instala la app como se describe a continuación:

1. En una línea de comandos, dirígete a android_sdk/tools/ e inicia el emulador especificando tu AVD.

   emulator -avd avd_name

   Si no sabes con certeza el nombre del AVD, ejecuta emulator -list-avds.

2. Ahora puedes instalar tu app mediante la herramienta adb o una de las tareas de instalación de Gradle que se mencionan en la sección para compilar un APK de depuración.

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

   adb install path/to/your_app.apk
   

   Se guardarán en project_name/module_name/build/outputs/apk/ todos los APK que compiles.

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 por 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 por USB, podrás instalar tu app con la herramienta adb o las tareas de instalación de Gradle que se mencionan en la sección sobre cómo compilar un APK de depuración.

adb -d install path/to/your_app.apk

Se guardarán en project_name/module_name/build/outputs/apk/ todos los APK que compiles.

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 debes compilar un paquete de aplicación desde la línea de comandos, puedes usar 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 crear un paquete firmado para subirlo a Play Console, primero debes configurar el archivo build.gradle.kts del módulo base con la información de firma de tu app. Para obtener más información, ve a la sección Cómo configurar Gradle para firmar tu app. Luego, podrás, por ejemplo, compilar la versión de lanzamiento de tu app, y Gradle generará automáticamente un paquete de aplicación y lo firmará con la información que proporciones en el archivo build.gradle.kts.

Si, en cambio, quieres que la firma de tu paquete de aplicación sea un paso separado, puedes usar jarsigner para firmar tu paquete de aplicación desde la línea de comandos. El comando para compilar un paquete de app es el siguiente:

jarsigner -keystore pathToKeystore app-release.aab keyAlias

Nota: No puedes usar apksigner para firmar tu paquete de aplicación.

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 a fin de 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 paquetes de app con bundletool y recrear localmente la manera en que Google Play genera los APK, por lo general, no necesitas invocar a bundletool para compilar el paquete de aplicación en sí. En su lugar, deberías usar las tareas de Gradle o Android Studio, como se describió en secciones anteriores.

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

En esta sección, se describe cómo empaquetar los recursos y códigos compilados de tu app, además de 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 que los recursos y el manifiesto de la app estén en el formato de búfer de protocolo de Google, también conocido como "protobuf", y este use la extensión de archivo *.pb. Los protobufs proporcionan un mecanismo extensible y neutral en cuanto al lenguaje y la plataforma para la serialización de datos estructurados. Su formato es similar a XML, pero más pequeño, más rápido y más simple.

Cómo descargar AAPT2

Puedes 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.

Precaución: No uses la versión de AAPT2 que se incluye en el paquete de herramientas de compilación de Android, ya que esta no admite bundletool.

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

1. Navega a com.android.tools.build > aapt2 en el í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.

Cómo compilar y vincular los recursos de tu app

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/

Nota: Si bien puedes pasar directorios de recursos a AAPT2 mediante la marca --dir, al hacerlo, se volverán a compilar todos los archivos del directorio, independientemente de cuántos se hayan modificado.

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 la marca --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

Nota: De manera alternativa, cuando especifiques los recursos compilados con la marca -R, podrás especificar un archivo de texto que incluya la ruta de acceso absoluta de cada uno de tus recursos compilados (con cada ruta de acceso separada por un solo espacio). Luego, puedes pasar ese archivo de texto a AAPT2 de la siguiente manera: aapt2 link ... -R @compiled_resources.txt.

A continuación, puedes extraer contenido del APK de salida, como AndroidManifest.xml, resources.pb y otros archivos de recursos de tu app, ahora en formato protobuf. Necesitarás esos 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 recursos y códigos previamente compilados

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 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 a los 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 tener los siguientes nombres: 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 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 pasarlo a bundletool a 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 compilar 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

Nota: Si quieres publicar el paquete de aplicación, deberás firmarlo con jarsigner. No puedes usar apksigner para firmar tu paquete de aplicación.

En la siguiente tabla, se describen con más detalles las marcas del comando build-bundle:

Marca	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 cómo personalizar 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 a fin de 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 de tu cadena de herramientas o tienda de aplicaciones. target-bundle-path especifica una ruta relativa a la raíz del paquete de aplicación donde te gustaría que 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 cuando se generan 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; luego, bundletool convierte y combina este archivo con la versión de protobuf incluida en cada paquete de aplicación.

Nota: Para obtener más información sobre cómo se asigna JSON al formato protobuf, lee Asginación de JSON. Sin embargo, esa información es más avanzada de lo necesario para esta página.

Por ejemplo, puedes controlar qué APK de categorías de configuración habilitar o inhabilitar. En el siguiente ejemplo de un archivo BundleConfig.json, se inhabilitan 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 base o de funciones):

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

En tu archivo BundleConfig.json, también puedes especificar qué tipo de archivos no deben comprimirse cuando se empaquetan los APK mediante patrones glob 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) ni la tabla de recursos (resources.arsc). Para ver la 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.

Cómo implementar tu app desde un paquete de aplicación

Si ya compilaste y firmaste un paquete de aplicación, usa bundletool para generar APK e implementarlos en un dispositivo.

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

No necesitas Android Studio para firmar tu app. Puedes firmarla desde la línea de comandos usando apksigner para APK o jarsigner para paquetes de aplicación, o puedes configurar Gradle para que lo firme durante la compilación. De cualquier manera, primero debes generar una clave privada mediante keytool, como se muestra a continuación:

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 almacén de claves y la clave, y a fin de 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 app 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 apps en la línea de comandos, usa jarsigner. Si, en cambio, 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 View > Tool Windows > Terminal y navega al directorio donde se encuentra el APK.

2. Alinea el APK sin firma usando 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 usando 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, incluidas la de un APK con archivos de clave y certificado privados separados, así como la 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 de las herramientas de compilación del SDK de Android o una posterior. 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.kts de nivel de módulo y agrega el bloque signingConfigs {} con entradas para storeFile, storePassword, keyAlias y keyPassword, y pasa ese objeto a la propiedad signingConfig en tu tipo de compilación. Por ejemplo:

Kotlin

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        create("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 {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            ...
        }
    }
}

Groovy

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
            ...
        }
    }
}

Nota: En este caso, se pueden ver el almacén de claves y la contraseña de clave directamente en el archivo build.gradle. Para una mayor seguridad, debes quitar la información de firmas de tu archivo de compilación.

Ahora, cuando compiles tu app invocando una tarea de Gradle, Gradle firmará tu app (y ejecutará zipalign) 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 deberías obtener más información sobre cómo publicar tu app y revisar la lista de tareas de lanzamiento para Google Play.