Cómo configurar tu compilación

El sistema de compilación de Android compila recursos y código fuente de la app, y los empaqueta en APKs o Android App Bundles que puedes probar, implementar, firmar y distribuir.

Android Studio usa Gradle, un paquete de herramientas de compilación avanzadas, para automatizar y administrar el proceso de compilación y, al mismo tiempo, definir configuraciones de compilación personalizadas y flexibles. Cada configuración de compilación puede definir su propio conjunto de código y recursos, y reutilizar las partes comunes a todas las versiones de tu app. El complemento de Android para Gradle funciona con el paquete de herramientas de compilación a fin de proporcionar procesos y ajustes configurables específicos para la compilación y prueba de apps para Android.

Gradle y el complemento de Android para Gradle se ejecutan independientemente de Android Studio. Por lo tanto, puedes compilar tus apps para Android desde Android Studio, la línea de comandos en tu máquina o en máquinas en las que no esté instalado Android Studio (como servidores de integración continua).

Si no usas Android Studio, puedes aprender a compilar y ejecutar tu app desde la línea de comandos. El resultado de la compilación es el mismo si compilas un proyecto desde la línea de comandos, en una máquina remota o con Android Studio.

Nota: Como Gradle y el complemento de Android para Gradle se ejecutan independientemente de Android Studio, debes actualizar las herramientas de compilación por separado. Lee las notas de la versión para descubrir cómo actualizar Gradle y el complemento de Android para Gradle.

La flexibilidad del sistema de compilación de Android te permite crear configuraciones de compilación personalizadas sin modificar los archivos de origen principales de tu app. Esta página te ayuda a comprender la manera en que funciona el sistema de compilación de Android y cómo puede ayudarte a personalizar y automatizar varias configuraciones de compilación. Si quieres obtener más información sobre cómo implementar tu app, consulta Cómo crear y ejecutar tu app. Para comenzar a crear configuraciones de compilación personalizadas de inmediato con Android Studio, consulta Cómo configurar variantes de compilación.

Proceso de compilación

En el proceso de compilación, se incluyen muchas herramientas y procesos que convierten tu proyecto en un paquete de aplicación para Android (APK) o un Android App Bundle (AAB).

El complemento de Android para Gradle realiza gran parte del proceso de compilación por ti, pero puede resultar útil comprender ciertos aspectos del proceso de compilación para que puedas ajustar la compilación de manera que cumpla con tus requisitos.

Los diferentes proyectos pueden tener diferentes objetivos de compilación. Por ejemplo, la compilación para una biblioteca de terceros produce bibliotecas Android Archive (AAR) o Java Archive (JAR). Sin embargo, una app es el tipo de proyecto más común, y la compilación para un proyecto de app produce un AAB o APK de depuración o lanzamiento de tu app que puedes implementar, probar o lanzar para usuarios externos.

Esta página se enfoca en el desarrollo de apps, pero muchos de los pasos y conceptos de compilación son comunes en la mayoría de los tipos de compilación.

Glosario de compilación de Android

Gradle y el complemento de Android para Gradle te ayudan a configurar los siguientes aspectos de tu compilación:

Tipos de compilación

Los tipos de compilación definen determinadas propiedades que Gradle usa cuando compila y empaqueta tu app, y por lo general están configurados para diferentes etapas de tu ciclo de vida de desarrollo.

Por ejemplo, el tipo de compilación de depuración habilita opciones de depuración y firma la app con la clave de depuración, mientras que el tipo de compilación de lanzamiento puede reducir, ofuscar y firmar tu app con una clave de lanzamiento para la distribución.

Debes definir al menos un tipo de compilación para poder compilar tu app; Android Studio crea los tipos de compilación de depuración y lanzamiento de forma predeterminada. Para comenzar a personalizar configuraciones de empaquetado para tu app, obtén información sobre cómo configurar tipos de compilaciones.

Variantes de productos
Las variantes de productos representan diferentes versiones de tu app que puedes lanzar para los usuarios, como las versiones gratuita y pagada. Puedes personalizar las variantes de productos para usar código y recursos diferentes mientras compartes y reutilizas las partes comunes en todas las versiones de tu app. Las variantes de productos son opcionales y debes crearlas de forma manual. Para comenzar a crear diferentes versiones de tu app, obtén información sobre cómo configurar variantes de productos.
Variantes de compilación
Una variante de compilación es un producto cruzado de un tipo de compilación y una variante de producto, y es la configuración que Gradle usa para compilar tu app. Con variantes de compilación, puedes compilar la versión de depuración de tus variantes de productos durante el desarrollo, o versiones de actualización firmadas de tus variantes de productos para distribución. Aunque no configuras variantes de compilación directamente, sí configuras los tipos de compilación y las variantes de productos que las forman. Cuando creas tipos de compilación o variantes de productos adicionales, también se crean variantes de compilación adicionales. Lee la descripción general Cómo configurar variantes de compilación para obtener información sobre cómo crearlas y administrarlas.
Entradas del manifiesto
Puedes especificar valores para algunas propiedades del archivo de manifiesto en la configuración de la variante de compilación. Estos valores de compilación anulan los valores existentes en el archivo de manifiesto, lo que resulta útil si deseas generar múltiples variantes de la app con un nombre de aplicación diferente, una versión de SDK mínima o una versión de SDK de destino. Cuando hay varios manifiestos, la herramienta de combinación de manifiestos combina la configuración de los manifiestos.
Dependencias
El sistema de compilación administra dependencias del proyecto desde tu sistema de archivos local y desde repositorios remotos. Esto significa que no tienes que buscar, descargar ni copiar manualmente paquetes binarios de tus dependencias en el directorio de tu proyecto. Para obtener más información, consulta Cómo agregar dependencias de compilación.
Firma
El sistema de compilación te permite especificar configuraciones de firma en la configuración de la compilación y puede firmar automáticamente tu app durante el proceso de compilación. El sistema de compilación firma la versión de depuración con una clave y un certificado predeterminados usando credenciales conocidas para evitar la solicitud de una contraseña durante el tiempo de compilación. El sistema de compilación no firma la versión de lanzamiento, a menos que definas explícitamente una configuración de firma para esta compilación. Si no tienes una clave de lanzamiento, puedes generar una como se describe en Cómo firmar tu app. Las compilaciones de lanzamiento firmadas son necesarias para distribuir apps a través de la mayoría de las tiendas de aplicaciones.
Reducción de código y recursos
El sistema de compilación te permite especificar un archivo de reglas ProGuard diferente para cada variante de compilación. Cuando compilas tu app, el sistema de compilación aplica el conjunto apropiado de reglas para reducir tu código y tus recursos usando las herramientas de reducción incorporadas, como R8. Reducir tu código y tus recursos puede ayudar a reducir el tamaño de tu APK o AAB.
Compatibilidad con varios APK
El sistema de compilación te permite compilar automáticamente diferentes APKs que contengan solo el código y los recursos necesarios para una densidad de pantalla o una interfaz binaria de la aplicación (ABI) específica. Para obtener más información, consulta Cómo compilar varios APKs. Sin embargo, se recomienda lanzar un solo AAB, ya que ofrece la división por lenguaje, además de la densidad de la pantalla y la ABI, y evita la necesidad de subir varios artefactos a Google Play. Todas las apps nuevas que se envíen después de agosto de 2021 deberán usar los AAB.

Versiones de Java en compilaciones de Android

Ya sea que tu código fuente esté escrito en Java, Kotlin o ambos, hay varios lugares en los que debes elegir una versión de lenguaje JDK o Java para tu compilación. Consulta Versiones de Java en compilaciones de Android para obtener más detalles.

Archivos de configuración de la compilación

Para crear configuraciones de compilación personalizadas, debes realizar cambios en uno o más archivos de configuración de compilación. Estos archivos de texto sin formato usan lenguaje específico de dominio (DSL) para describir y manipular la lógica de compilación con la secuencia de comandos de Kotlin, que es una variante del lenguaje Kotlin. También puedes usar Groovy, un lenguaje dinámico para la máquina virtual Java (JVM), a fin de configurar tus compilaciones.

No necesitas conocer la secuencia de comandos de Kotlin o Groovy para comenzar a configurar tu compilación, ya que el complemento de Android para Gradle contiene la mayoría de los elementos DSL que necesitas. Para obtener más información sobre el DSL del complemento de Android para Gradle, lee la documentación de referencia de DSL. La secuencia de comandos de Kotlin también se basa en el DSL de Kotlin de Gradle subyacente.

Cuando comienzas un proyecto nuevo, Android Studio crea automáticamente algunos de estos archivos y los completa según valores predeterminados sensibles. La estructura de archivos de proyecto tiene el siguiente diseño:

└── MyApp/  # Project
    ├── gradle/
    │   └── wrapper/
    │       └── gradle-wrapper.properties
    ├── build.gradle(.kts)
    ├── settings.gradle(.kts)
    └── app/  # Module
        ├── build.gradle(.kts)
        └── build/
            ├── libs/
            └── src/
                └── main/  # Source set
                    ├── java/
                    │   └── com.example.myapp
                    ├── res/
                    │   ├── drawable/
                    │   ├── values/
                    │   └── ...
                    └── AndroidManifest.xml

Hay algunos archivos de configuración de compilación de Gradle que forman parte de la estructura estándar del proyecto para una app para Android. Antes de comenzar a configurar tu compilación, es importante que comprendas el alcance y el propósito de cada uno de esos archivos, y los elementos de DSL básicos que definen.

El archivo de wrapper de Gradle

El wrapper de Gradle (gradlew) es una aplicación pequeña que se incluye con tu código fuente que descarga e inicia Gradle. Esto crea una ejecución de compilación más coherente. Los desarrolladores descargan la fuente de la aplicación y ejecutan gradlew. Esta acción descarga la distribución de Gradle requerida y, luego, inicia Gradle para compilar tu aplicación.

El archivo gradle/wrapper/gradle-wrapper.properties contiene una propiedad, distributionUrl, que describe qué versión de Gradle se usa para ejecutar la compilación.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Archivo de configuración de Gradle

El archivo settings.gradle.kts (para el DSL de Kotlin) o el archivo settings.gradle (para el DSL de Groovy) se encuentra en el directorio raíz del proyecto. Ese archivo de configuración define la configuración del repositorio en el nivel de proyecto y le informa a Gradle qué módulos debe incluir al compilar tu app. Los proyectos de varios módulos deben especificar cada módulo que formará parte de la compilación final.

En la mayoría de los proyectos, el archivo tiene el siguiente aspecto predeterminado:

Kotlin

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

Groovy

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

Archivo de compilación de nivel superior

El archivo build.gradle.kts de nivel superior (para el DSL de Kotlin) o el archivo build.gradle (para el DSL de Groovy) se encuentra en el directorio raíz del proyecto. Por lo general, define las versiones comunes de los complementos que usan los módulos de tu proyecto.

En la siguiente muestra de código, se describen la configuración predeterminada y los elementos de DSL en la secuencia de comandos de compilación de nivel superior después de crear un proyecto nuevo:

Kotlin

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "8.3.0" apply false
    id("com.android.library") version "8.3.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.20" apply false
}

Groovy

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '8.3.0' apply false
    id 'com.android.library' version '8.3.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}