Kotlin DSL: build.gradle.kts, el bloque android y la migración desde Groovy

Durante una década los ficheros de compilación de Android se escribieron en Groovy, un lenguaje dinámico donde cualquier símbolo podía significar cualquier cosa y el IDE no tenía forma honesta de ayudarte. Escribías complieSdk en lugar de compileSdk y el build no fallaba: Groovy interpretaba la línea como una llamada a un método desconocido que el DSL absorbía en silencio, y descubrías el problema tres pantallas más abajo con un error incomprensible. El DSL de Kotlin cambia la premisa de raíz: tu build.gradle.kts es un fichero Kotlin que se compila antes de ejecutarse, contra un modelo de tipos generado a partir de los plugins que has aplicado. Lo que ganas no es sintaxis más bonita —de hecho es algo más verbosa— sino que el compilador y el IDE por fin sepan de qué estás hablando.

Qué es realmente un DSL de tipos seguros

Un DSL en Gradle no es magia sintáctica: es una función que recibe una lambda con receptor. Cuando escribes un bloque android seguido de llaves, estás llamando a una función llamada android cuyo único argumento es una lambda cuyo this implícito es un objeto de configuración. Dentro de esa lambda, cada línea que parece una declaración es en realidad una asignación a una propiedad o una llamada a un método de ese receptor. Esa es toda la mecánica, y entenderla convierte el fichero de un conjunto de fórmulas memorizadas en código que puedes razonar.

// La firma real, simplificada: una funcion de extension sobre Project que
// recibe una lambda con receptor de tipo ApplicationExtension
fun Project.android(configurar: ApplicationExtension.() -> Unit)

// Por eso dentro del bloque el this implicito es la propia extension,
// y cada linea es una asignacion o una llamada sobre ese receptor
android {
    // this: ApplicationExtension
    compileSdk = 36
    defaultConfig {
        // this: ApplicationDefaultConfig
        minSdk = 26
    }
}

La diferencia con Groovy no es estética. En Groovy, android era una llamada a un método interceptado dinámicamente y las propiedades se resolvían por nombre en tiempo de ejecución; nada podía verificarse antes. En Kotlin, android es una función de extensión real cuyo tipo receptor depende del plugin aplicado —ApplicationExtension para un módulo de aplicación, LibraryExtension para una biblioteca— y por eso el autocompletado funciona, la navegación al código fuente funciona y un nombre mal escrito es un error de compilación antes de que se ejecute nada.

Anatomía de un módulo de aplicación

Un fichero de compilación de Android moderno tiene tres bloques mayores y un orden que no es arbitrario: primero se declaran los plugins, porque son los que introducen las extensiones; después se configura la extensión que esos plugins han aportado; por último se declaran las dependencias.

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
}

android {
    namespace = "com.ejemplo.app"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.ejemplo.app"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }

    buildFeatures {
        compose = true
        buildConfig = true
    }

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

kotlin {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
    }
}

dependencies {
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.compose.material3)
}

Cuatro detalles merecen comentario. namespace es el paquete que usan R y BuildConfig, y desde hace varias versiones vive aquí y no en el manifiesto. applicationId es una cosa distinta: es la identidad de la app en el dispositivo y en Google Play, y puede diferir del namespace —de hecho lo hará en cuanto uses sabores—. compileSdk es la versión de la API contra la que compilas y debe ser la más reciente estable; minSdk y targetSdk son promesas de comportamiento en tiempo de ejecución, no de compilación. Y buildFeatures es un interruptor de generación de código: cada bandera que activas añade tareas al grafo, así que activar solo lo que usas es una decisión de rendimiento, no de estilo.

El orden de las capas y quién configura qué

Conviene tener presente de dónde sale cada bloque, porque la confusión habitual —creer que android es una palabra clave de Gradle— desaparece en cuanto ves la cadena de causalidad.

flowchart TD
S[settings punto gradle punto kts declara repositorios y modulos] --> P[bloque plugins aplica el plugin de aplicacion de Android]
P --> E[el plugin registra la extension ApplicationExtension]
E --> A[el bloque android configura esa extension]
A --> T[el plugin traduce la configuracion en tareas y variantes]
P --> D[el plugin tambien registra configuraciones como implementation]
D --> Q[el bloque dependencies usa esas configuraciones]
style S fill:#89b4fa,color:#11111b
style E fill:#cba6f7,color:#11111b
style T fill:#a6e3a1,color:#11111b

Lo que este diagrama deja claro es que no puedes configurar android sin haber aplicado antes el plugin, ni usar implementation sin que algún plugin haya registrado esa configuración. El orden de los bloques dentro del fichero importa por esta razón concreta y no por otra: plugins va primero porque es quien crea el vocabulario que el resto del fichero usa. Y también explica por qué settings.gradle.kts es un fichero aparte con sus propias reglas: se evalúa en la fase de inicialización, antes de que exista ningún proyecto que configurar, y por eso allí se declaran los repositorios y los módulos participantes y no dependencias.

Migrar desde Groovy sin detener el mundo

La migración no exige un día de parada. Gradle acepta que unos módulos usen build.gradle y otros build.gradle.kts en el mismo proyecto, así que la estrategia sensata es empezar por settings.gradle, seguir por los módulos hoja —los que menos lógica tienen— y dejar el raíz y el de la aplicación para el final, cuando ya domines las reglas.

Las traducciones mecánicas son cuatro y cubren la inmensa mayoría del trabajo. Las cadenas pasan de comillas simples a comillas dobles. Las asignaciones a propiedades exigen el signo igual explícito, donde Groovy lo omitía. Las llamadas a métodos exigen paréntesis, también donde Groovy los omitía; la trampa está en distinguir cuál es cuál, porque en Groovy ambas cosas se escribían igual. Y def desaparece en favor de val.

// Groovy                     ->  Kotlin DSL
// compileSdk 36              ->  compileSdk = 36            (propiedad)
// implementation 'g:a:1.0'   ->  implementation("g:a:1.0")  (metodo)
// def x = 1                  ->  val x = 1

// Tareas: registro perezoso y tipado
tasks.register<Copy>("copiarNotas") {
    from(layout.projectDirectory.dir("notas"))
    into(layout.buildDirectory.dir("notas"))
}

// Propiedades del proyecto y del entorno, sin romper la cache de configuracion
val esCi: Boolean = providers.environmentVariable("CI").isPresent
val sabor: String = providers.gradleProperty("saborPorDefecto").getOrElse("dev")

Hay tres trampas que causan casi todos los tropiezos. La primera es la resolución de tareas: en Groovy escribías el nombre de una tarea y aparecía; en Kotlin necesitas tasks.named o el operador de delegación, y conviene usar la variante tipada para poder configurar propiedades específicas. La segunda son los ext de Groovy para versiones compartidas, que no tienen traducción idiomática y no deben tenerla: su sustituto correcto es el catálogo de versiones que estudiarás en la siguiente lección. La tercera es leer propiedades del sistema o del entorno con las APIs de Java, que rompe la caché de configuración; usa siempre providers como en el ejemplo anterior.