build.gradle: qué es, sintaxis y configuración en Android

¿Qué es build.gradle?

build.gradle es un script de compilación en lenguaje Groovy (extensión .gradle) o Kotlin (.gradle.kts) que gestiona todos los aspectos de la compilación de una aplicación Android. Gradle es un sistema de compilación automática adoptado por Google en 2013 como estándar para Android. build.gradle describe: qué plugins están aplicados (Android, Kotlin, bibliotecas), qué dependencias están conectadas, qué versiones de SDK se usan, cómo firmar la aplicación y dónde publicar.

El proceso de compilación incluye tres fases: Initialization (descubrimiento de módulos), Configuration (ejecución de scripts build.gradle), Execution (ejecución de tareas). build.gradle se ejecuta durante la fase Configuration, cuando Gradle crea el grafo de tareas. En este momento se determinan los Build Variants, se calculan las dependencias y se configuran las tareas. Importante: build.gradle es código, no solo configuración. En él se pueden usar condiciones, bucles, llamadas a métodos y scripts externos.

Los archivos Gradle se almacenan en la raíz del módulo (app/build.gradle) y la raíz del proyecto (build.gradle). Además, Gradle admite apply from — inclusión de scripts Gradle externos. Esto permite extraer lógica repetitiva en archivos con configuraciones compartidas. Con la llegada de los Convention Plugins (AGP 7+), apply from se considera obsoleto — los Convention Plugins proporcionan una forma type-safe y componible de reutilizar configuración entre módulos.

Evolución de build.gradle

Desde 2013, la sintaxis de build.gradle ha experimentado cambios significativos: desde Groovy con configuraciones dinámicas hasta Kotlin DSL con verificaciones en tiempo de compilación. AGP ha evolucionado desde la versión 1.0 hasta 8.7 (2025). Hitos clave: AGP 3.0 (Java 8 desugar, nueva variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL por defecto, Java 11 mínimo), AGP 8.0 (clases R no transitivas, build config en Kotlin), AGP 8.7 (KSP en lugar de kapt, configuración rápida).

Project-level y Module-level build.gradle

Project-level build.gradle (raíz) define plugins, repositorios y configuraciones comunes a todos los módulos. Bloques principales: plugins (declaraciones de plugins Gradle), repositories (fuentes de dependencias: mavenCentral, google, jitpack). El build.gradle raíz normalmente no tiene bloque android — aparece en los módulos. Project-level también puede contener un bloque subprojects para configuración común de todos los subproyectos, aunque los Convention Plugins son preferibles.

Module-level build.gradle (por ejemplo, app/build.gradle) describe un módulo específico. Si el módulo es una aplicación, aplica el plugin com.android.application. Si es una biblioteca — com.android.library. Module-level contiene: bloque android (compileSdk, defaultConfig, buildTypes, productFlavors), bloque dependencies (dependencias del módulo) y opcionalmente bloques para configuración de pruebas y empaquetado. Module-level se ejecuta después de project-level y puede sobrescribir configuraciones comunes.

A partir de AGP 8.0, el build.gradle raíz puede usar version catalogs (libs.versions.toml) para la gestión centralizada de versiones de dependencias. Un version catalog es un archivo en el directorio gradle/ que contiene versiones, bibliotecas y plugins. En build.gradle las dependencias se conectan mediante libs: implementation(libs.retrofit). Los version catalogs son obligatorios para proyectos nuevos y recomendados para todos los proyectos con tres o más módulos.

// settings.gradle.kts — raíz del proyecto
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (project-level)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (module-level)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy vs Kotlin DSL

Groovy es un lenguaje JVM dinámico que fue la sintaxis original de Gradle. Los scripts Groovy (.gradle) usan tipado dinámico: se pueden omitir tipos, usar cadenas con o sin comillas, llamar a métodos que no existen en tiempo de compilación. La flexibilidad de Groovy es también su defecto: el IDE no puede verificar sintaxis y tipos hasta que el script se ejecuta, lo que genera errores en tiempo de ejecución por nombres de parámetros o tipos incorrectos.

Kotlin DSL (.gradle.kts) usa el tipado estático de Kotlin. El IDE verifica tipos, sugiere parámetros disponibles mediante autocompletado y resalta errores en tiempo de edición. Kotlin DSL es más lento durante la fase Configuration (debido a la compilación de archivos .kts a bytecode), pero Google mejora continuamente el rendimiento: AGP 8.5+ usa Gradle Configuration Cache y Caching Kotlin DSL compilation, reduciendo la diferencia a 1-2 segundos.

Google recomienda Kotlin DSL para todos los proyectos nuevos y la migración gradual de los existentes. La migración de Groovy a Kotlin DSL es directa: las comillas se reemplazan por paréntesis, se añaden tipos, los operadores se convierten en funciones. La mayoría de las bibliotecas proporcionan ejemplos de Kotlin DSL en su documentación. Para casos complejos (Custom Plugin, Task Graph), Kotlin DSL proporciona una API type-safe y previene errores que en Groovy solo se descubren en tiempo de ejecución. Los version catalogs (libs.versions.toml) funcionan igual con ambas sintaxis.

Bloque android: configuración de la aplicación

compileSdk, minSdk y targetSdk

Bloque android es el elemento central de module-level build.gradle. Dentro se configuran: namespace (para R y BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Todos los parámetros del bloque android se aplican solo a módulos Android. Si el módulo es una biblioteca, se usa el plugin de biblioteca en lugar de application, y applicationId está ausente del bloque android.

compileSdk es la versión del SDK con la que se compila el código. Debe ser la última API de Android (en el momento de escribir — 35). minSdk es la versión mínima de API compatible. targetSdk es la versión a la que se dirige la aplicación (se aplican los cambios de comportamiento de esta versión). La diferencia entre compileSdk y targetSdk: compileSdk determina las API disponibles, targetSdk determina el comportamiento en tiempo de ejecución. Recomendación: compileSdk = latest, targetSdk = latest - 1 (para probar la adaptación a nuevos cambios).

compileOptions establece la compatibilidad de Java: sourceCompatibility y targetCompatibility. AGP 8+ requiere Java 17+ para compilar. packaging gestiona la inclusión de archivos de bibliotecas: exclude, merge, pickFirst para resolver conflictos META-INF. buildFeatures activa/desactiva ViewBinding, DataBinding, Compose. aaptOptions configura el procesamiento de recursos: ignoreAssetsPattern, cruncherEnabled. Cada elemento del bloque android optimiza un aspecto específico de la compilación.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

Gestión de dependencias

BOM (Bill of Materials)

Dependencias en build.gradle son bibliotecas y módulos que se conectan al proyecto. El bloque dependencies está al mismo nivel que el bloque android. Gradle admite varias configuraciones: implementation (la biblioteca está disponible en este módulo, no es transitiva), api (la biblioteca está disponible transitivamente para los módulos dependientes), compileOnly (solo para compilación, no se incluye en APK), runtimeOnly (solo en tiempo de ejecución), annotationProcessor / ksp (procesadores de anotaciones), testImplementation (solo para pruebas), androidTestImplementation (solo para pruebas instrumentalizadas).

A partir de AGP 8.0, Clases R no transitivas — cada biblioteca tiene su propia clase R, lo que previene conflictos de recursos. En el bloque dependencies es importante usar las configuraciones correctas: implementation no expone dependencias transitivas, acelerando la compilación. api las expone — se usa cuando una biblioteca exporta tipos de otra biblioteca (por ejemplo, Retrofit usa tipos de OkHttp en su API pública).

Para la gestión de versiones se recomienda usar BOM (Bill of Materials) — un archivo de compilación que define versiones compatibles de bibliotecas. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Tras conectar BOM, se puede especificar solo el nombre de la biblioteca sin versión — BOM seleccionará automáticamente una versión compatible. Esto elimina conflictos entre dependencias transitivas de diferentes bibliotecas. Los BOM están disponibles para Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — gestión de versiones
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX y Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (versiones de BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle en proyectos multimódulo

En proyectos multimódulo, cada módulo tiene su propio build.gradle. Para conectar un módulo con otro se usa la sintaxis implementation(project(":module-name")). Gradle recompila automáticamente el módulo si su configuración ha cambiado. La arquitectura multimódulo mejora el tiempo de compilación (compilación incremental, paralelismo) y separa responsabilidades entre módulos de funcionalidad, módulos centrales y bibliotecas.

El problema clave de los proyectos multimódulo es la duplicación de configuración. Si 10 módulos tienen el mismo minSdk, compileSdk y dependencias de Compose, son 10 copias en diferentes build.gradle. La solución son los Convention Plugins (anteriormente buildSrc). Un Convention Plugin es un plugin de Gradle escrito en Kotlin que se aplica a los módulos: plugins { id("myapp.android.library") }. El plugin contiene configuración común y los cambios se aplican inmediatamente a todos los módulos.

Para organizar los Convention Plugins se usa el directorio build-logic/ en la raíz del proyecto. Contiene includeBuild en settings.gradle y plugins Kotlin. Los Convention Plugins pueden publicarse en un repositorio maven para su reutilización entre proyectos. Google recomienda Convention Plugins como estándar para proyectos multimódulo, reemplazando subprojects { } y apply from. La migración a Convention Plugins reduce el build.gradle del módulo a 10-15 líneas.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — después de Convention Plugin
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}