Los ficheros de Gradle de tu proyecto

En Tu primer proyecto en Kotlin y en Variables, tipos y operaciones ejecutaste tu main() con lo mínimo de Gradle. Esta lección te da el mapa de los ficheros de Gradle que Android Studio ha creado, con una frase para cada uno, y te enseña lo único que vas a tocar ya: el catálogo de versiones y cómo se instala una librería. Lo harás aquí una vez; cada lección que necesite una librería nueva repetirá la receta en corto.

Al terminar, :torneo compilará con el JDK 17 y con Kotlin 2.4.20, y tendrá instalada la librería de tests, lista para escribir tu primer test en Bucles y tu primer test.

El mapa: los ficheros de Gradle

Gradle es la herramienta que convierte tus .kt en una app que se instala: compila (traduce tu código a instrucciones que el ordenador ejecuta), descarga librerías, empaqueta y ejecuta tests. A todo ese proceso se le llama un build (construcción), y por eso al final de cada ejecución ves BUILD SUCCESSFUL. No le das órdenes: le describes en unos ficheros qué quieres construir, como la receta que lee un cocinero. Son programas en Kotlin (el Kotlin DSL que elegiste al crear el proyecto) y acaban en .gradle.kts.

Dos palabras que verás en seguida: un plugin es un complemento que enseña a Gradle a hacer algo nuevo (construir una app Android, por ejemplo), y una dependencia es una librería que tu código usa y Gradle descarga. Una librería es código que alguien ya escribió y empaquetó para que otros lo usen sin escribirlo de nuevo.

Todos los ficheros están en la vista Android, dentro de Gradle Scripts, cada uno con una etiqueta gris entre paréntesis. Una frase por cada uno; solo los marcados con tocas los abrirás hoy, y el resto los verás cuando haga falta:

• build.gradle.kts (Project: Marcador): la lista de plugins del proyecto entero. No construye nada. Lo verás cuando instales tu primer plugin.
• build.gradle.kts (Module :app): la ficha de la app Android (su identificador, versiones de Android, dependencias). Lo verás en las lecciones de Android.
• build.gradle.kts (Module :torneo): la ficha de :torneo. Tocas.
• settings.gradle.kts (Project Settings): qué módulos existen (include(":app"), include(":torneo")) y de qué repositorios (almacenes de librerías y plugins, como google() y mavenCentral()) se descarga todo.
• libs.versions.toml (Version Catalog "libs"): el catálogo, donde se escriben las versiones de todo. Tocas.
• gradle.properties (hay dos, Project Properties y Global Properties): ajustes de Gradle en forma clave=valor.
• gradle-wrapper.properties (Gradle Version): qué versión de Gradle usa el proyecto, en la línea distributionUrl. Por eso se ejecuta ./gradlew y no gradle: gradlew es el wrapper (el «envoltorio»), un lanzador que viene dentro del proyecto y baja esa versión por ti, así que todos compilan con la misma.
• gradle-daemon-jvm.properties: qué Java usa el propio Gradle para funcionar (si no lo ves en Gradle Scripts, no pasa nada: no lo vas a abrir). Lo escribe la plantilla; no se toca.
• local.properties (SDK Location): la ruta del SDK de Android en tu ordenador. La escribe Android Studio; no se toca.

Una cosa más, sobre Java. Java es otro lenguaje de programación que corre en la misma máquina (la JVM) que Kotlin, y el JDK es el kit que instala esa máquina y las herramientas para compilar; lo instalaste en JDK y verificación del entorno. Hay dos en juego: Gradle corre sobre el suyo, el de gradle-daemon-jvm.properties, que Gradle descarga solo, y el que compila y ejecuta tu código es el JDK 17 que instalaste tú.

El catálogo de versiones: la agenda de contactos

Una app usa decenas de librerías y varios módulos comparten muchas. Si cada build.gradle.kts escribiera "junit:junit:4.13.2", subir una versión obligaría a buscarla en todos. El catálogo es la agenda del móvil: cada versión, librería y plugin se escribe una vez, con un nombre llamado alias, y los build.gradle.kts llaman por el nombre. (Sin catálogo, cada librería se escribiría con sus coordenadas: grupo, nombre y versión separados por dos puntos, como junit:junit:4.13.2, que es el grupo junit, la librería junit y su versión.)

Ábrelo en Gradle Scripts → libs.versions.toml (Version Catalog "libs"). Es TOML: texto plano clave = valor con secciones entre corchetes, y los comentarios empiezan por # (en Kotlin eran //). Las que usarás son tres: [versions] (los números), [libraries] (las librerías) y [plugins] (los plugins). Este es un extracto (los «…» son líneas que tu fichero tiene y aquí se omiten), con las dos líneas que añadió el asistente al crear :torneo marcadas:

[versions]                    # los NÚMEROS, escritos en camelCase (ver abajo)
agp = "9.4.1"                 # AGP (Android Gradle Plugin): el plugin que construye apps Android
coreKtx = "1.19.1"
junit = "4.13.2"                # JUnit 4: la librería de tests que trae la plantilla para `:app`
# … más versiones de la plantilla …
kotlin = "2.2.10"
composeBom = "2026.02.01"     # la versión de Compose, la librería con la que se dibujan las pantallas
jetbrainsKotlinJvm = "2.2.10" # la añadió el asistente al crear :torneo
 
[libraries]                   # las LIBRERÍAS: alias en minúsculas con guiones
# group (quién la publica) + name (cuál) + version.ref: «la versión es la que se llama coreKtx arriba»
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
# … más librerías de la plantilla …
 
[plugins]                     # los PLUGINS: igual, con el id del plugin en lugar de las coordenadas
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
jetbrains-kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "jetbrainsKotlinJvm" }   # la añadió el asistente

camelCase es escribir varias palabras juntas, cada una con mayúscula salvo la primera: composeBom, coreKtx. Los números de [versions] se escriben así.

JUnit es una librería para escribir y ejecutar tests. La junit 4 del catálogo es la que usa :app; la que instalarás para :torneo, kotlin-test, funciona por debajo con JUnit 5, otra versión del mismo motor. Son dos cosas distintas y no se mezclan.

El catálogo se llama libs (por el nombre del fichero) y cada guion del alias pasa a ser un punto, que Android Studio autocompleta. Así se usa un alias en un build.gradle.kts:

implementation(libs.androidx.core.ktx)          // [libraries] androidx-core-ktx: cuelga directamente de libs (`implementation` se explica en la sección siguiente)
alias(libs.plugins.jetbrains.kotlin.jvm)        // [plugins] jetbrains-kotlin-jvm: cuelga de libs.plugins

En el editor, escribe libs. y Android Studio te propone los alias disponibles.

El bloque dependencies y Sync

Las librerías que usa un módulo se declaran en el bloque dependencies { } de su build.gradle.kts. Mira el de la app, en Gradle Scripts → build.gradle.kts (Module :app), sin cambiarlo:

dependencies {
    // La palabra de delante dice CUÁNDO hace falta la librería:
    implementation(libs.androidx.core.ktx)   // implementation: para compilar y ejecutar el módulo (androidx es el grupo de librerías de Google para Android)
    testImplementation(libs.junit)           // testImplementation: solo en los tests que corren en tu ordenador
    // … el resto de la plantilla; otras palabras como esta las verás cuando las uses
}

Una librería de tests puesta con implementation acabaría dentro de la app publicada sin hacer nada: elegir bien la palabra importa.

Sync es el momento en que Gradle relee estos ficheros y descarga lo nuevo. Cada vez que cambias uno, Android Studio enseña arriba del editor un aviso con el enlace Sync Now: púlsalo y espera a que termine sin errores rojos.

[versions]
precios = "2.0.1"        # el número, con su propia clave
 
[libraries]
tienda-precios = { group = "com.ejemplo.tienda", name = "precios", version.ref = "precios" }

dependencies {
    implementation(libs.tienda.precios)   // implementation: la usa el código normal, no solo los tests
}

Paso · Ajusta las versiones al curso

Objetivo: que el proyecto compile con Kotlin 2.4.20 y la versión de Compose del curso, con un solo número para Kotlin.

El asistente escribe las versiones que conocía el día que se publicó. El curso usa Kotlin 2.4.20 (la plantilla trae 2.2.10) y 2026.08.00 para Compose (la plantilla trae 2026.02.01).

En [versions], cambia solo estos dos números. Una versión es el número que lleva cada entrega de una librería: 2.4.20 es más nueva que 2.2.10. Fijarla garantiza que todos usen exactamente el mismo código.

kotlin = "2.2.10"
composeBom = "2026.02.01"

kotlin = "2.4.20"            # el compilador de Kotlin que usa el curso
composeBom = "2026.08.00"    # la versión de Compose que usa el curso

Ahora, la trampa del asistente. El catálogo tiene dos números para lo mismo: kotlin y jetbrainsKotlinJvm, los dos el compilador de Kotlin. Si no coinciden, Gradle no da error: se queda con el más alto, y el 2.2.10 que sigue escrito miente. Cada número debe estar escrito una sola vez, así que haz que el plugin use kotlin:

1. En [plugins], en la línea de jetbrains-kotlin-jvm, cambia version.ref = "jetbrainsKotlinJvm" por version.ref = "kotlin".
2. En [versions], borra la línea jetbrainsKotlinJvm = "2.2.10", que ya no usa nadie.

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
jetbrains-kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }   # antes: version.ref = "jetbrainsKotlinJvm"

El alias jetbrains-kotlin-jvm no cambia: es el nombre que escribió Android Studio. Pulsa Sync Now; debe terminar sin rojo (si no, la caja «Si Sync sale en rojo» de más abajo).

Paso · Fija el JDK 17 en :torneo

Objetivo: que :torneo se compile siempre con el JDK 17.

Abre Gradle Scripts → build.gradle.kts (Module :torneo). El asistente pidió Java 11 dos veces, una para el compilador de Java (java { … }) y otra para el de Kotlin (compilerOptions { … }). Borra el bloque java { … } entero y el compilerOptions { … } de dentro de kotlin, y deja kotlin así:

kotlin {
    jvmToolchain(17)   // «este módulo se compila con el JDK 17», una sola vez
}

Ya que estás en este fichero, borra también la línea id("java-library") del bloque plugins: la puso el asistente, pero con el plugin de Kotlin y application no hace falta.

Pulsa Sync Now y ejecuta de nuevo ./gradlew :torneo:run: debe imprimir las mismas tres líneas.

Paso · Instala tu primera librería: kotlin-test

Objetivo: que :torneo tenga la librería de tests de Kotlin. La usarás en Bucles y tu primer test para escribir tu primer test.

Esta es la receta para instalar cualquier librería. Léela despacio una vez.

1 · Qué instalas y por qué ahora. kotlin-test es la librería oficial de Kotlin para escribir tests. Un test es un trozo de código que comprueba que otro trozo da el resultado esperado; escribirás el primero en Bucles y tu primer test. La librería trae @Test, una etiqueta que marca cuál es un test, y comprobaciones como assertEquals. Se instala ahora para no interrumpir esa lección con configuración.

2 · La versión, en [versions]. Primero se busca si el catálogo ya tiene el número. kotlin-test se publica junto al compilador, con su misma versión, y ese número ya está: kotlin. No añades nada. Si fuera una librería con su propia versión, escribirías aquí una línea nueva, en camelCase: nombreDeLaLibreria = "1.2.3".

3 · La librería, en [libraries]. Añade esta línea al final de esa sección, antes de la cabecera [plugins]:

kotlin-test = { group = "org.jetbrains.kotlin", name = "kotlin-test", version.ref = "kotlin" }

El alias, kotlin-test, va en minúsculas con guiones como el resto. Cada cosa va en su sección: una librería nunca en [plugins], ni un número suelto en [libraries]. (Los plugins se instalan con un paso más; lo verás en JSON e instalar kotlinx.serialization, cuando instales el primero.)

4 · La dependencia, en el módulo que la usa. En build.gradle.kts (Module :torneo), añade al final del fichero:

dependencies {
    testImplementation(libs.kotlin.test)   // la librería, solo para los tests
}
tasks.test {
    useJUnitPlatform()                     // los tests se ejecutan con JUnit 5, el motor que usa kotlin-test
}

• testImplementation porque solo la usan los tests: no entra en el programa. Si la usara el código normal, sería implementation.
• libs.kotlin.test es el alias kotlin-test con el guion convertido en punto.
• tasks.test { useJUnitPlatform() } le dice a la tarea test que ejecute los tests con JUnit 5, el motor que hay debajo de kotlin-test (JUnit es la biblioteca de tests más usada de la JVM). No hace falta que entiendas por dentro esa línea ni las llaves que la rodean: es una línea fija que se copia tal cual.

5 · Sync Now, y comprueba. Pulsa Sync Now. Debe terminar sin errores rojos. La comprobación final llega en Bucles y tu primer test, cuando escribas import kotlin.test.Test en un test y Android Studio lo reconozca.

Verás en otros proyectos la forma corta testImplementation(kotlin("test")): declara la misma librería sin pasar por el catálogo. En las lecciones de Marcador las librerías pasan por el catálogo, para que cada versión esté en un solo sitio. Android Studio también puede escribir estas líneas por ti (File → Project Structure…, apartado de dependencias del módulo); aprenderlo a mano primero te permite leer y arreglar lo que escriba el IDE. El IDE es el editor donde programas, aquí Android Studio.

Con estos cambios, :app sigue compilando: no la has tocado. Para comprobarlo, ejecuta en la Terminal ./gradlew :app:assembleDebug; debe acabar con BUILD SUCCESSFUL.

Para comparar con el tuyo (no lo pegues), así queda build.gradle.kts (Module :torneo) completo:

plugins {
    alias(libs.plugins.jetbrains.kotlin.jvm)    // el compilador de Kotlin, con la versión del catálogo
    application                                 // permite ejecutarlo con ./gradlew :torneo:run
}
kotlin {
    jvmToolchain(17)                            // se compila con el JDK 17
}
application {
    mainClass.set("com.sebastiannarvaez.marcador.torneo.MainKt")   // dónde está el main(): Main.kt → MainKt
}
dependencies {
    testImplementation(libs.kotlin.test)        // kotlin-test, solo para los tests
}
tasks.test {
    useJUnitPlatform()                          // los tests corren con JUnit 5
}