Skip to main content

Configuraciones globales

⏱ Dedicación recomendada: 0 minutos
Esto considera el contenido visible y relevante, e ignora texto colapsado o marcado como opcional.

r8vnhill/echo-app-kt

Antes de continuar con tareas más avanzadas como la organización en módulos o la publicación de artefactos, es importante establecer una configuración global clara y coherente para el proyecto. Esto asegura que todos los submódulos compartan valores comunes, evita repeticiones y mejora el rendimiento general de Gradle.

En esta lección aprenderás a usar el archivo gradle.properties para definir propiedades reutilizables —como la cantidad de memoria asignada a la JVM, el uso de la caché de tareas o el identificador del grupo del proyecto— y a referenciar esas propiedades desde build.gradle.kts. Esta práctica es fundamental para mantener un proyecto limpio, mantenible y preparado para escalar.

🆔 ¿Qué es el grupo del proyecto?​

El grupo en Gradle es una cadena que identifica de forma única a un proyecto dentro de un ecosistema de artefactos.
Por convención, se utiliza un formato de dominio invertido (por ejemplo, cl.ravenhill) para evitar colisiones con proyectos de otras personas u organizaciones.

Este valor se combina con el nombre del proyecto y su versión para generar el identificador completo del artefacto, que se utiliza al publicarlo en un repositorio.

¿Y si no tengo un dominio?

No necesitas tener un dominio propio. Una alternativa común es usar tu nombre de usuario de GitHub en el formato
com.github.username.

🧾 gradle.properties​

Para mantener las configuraciones globales de forma organizada y centralizada, crearemos un archivo llamado gradle.properties en la raíz del proyecto. Este archivo permite definir propiedades reutilizables en todos los archivos de configuración, tanto para parámetros de ejecución como para variables globales o de entorno.

gradle.properties
# Parámetros de la JVM
org.gradle.jvmargs=-Xmx4g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
systemProp.org.gradle.jvmargs=-Xmx4g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

# Configuraciones de rendimiento
org.gradle.caching=true
org.gradle.parallel=true
org.gradle.daemon=true

# Grupo del proyecto (ajusta según tu dominio o nombre de usuario)
echo.group = cl.ravenhill
¿Qué acabamos de hacer?
  • org.gradle.jvmargs: Configura los argumentos de la JVM usados por Gradle. En este caso, asigna un máximo de 4 GB de memoria y habilita el volcado de heap en caso de error de memoria.
  • org.gradle.caching, org.gradle.parallel, org.gradle.daemon: Activan optimizaciones importantes como la caché de tareas, ejecución en paralelo y el uso de un daemon para mantener Gradle en memoria entre ejecuciones.
  • echo.group: Propiedad personalizada que define el grupo del proyecto. Se reutiliza en build.gradle.kts para establecer un identificador único del artefacto.
🔍 ¿Dónde busca Gradle las propiedades?

Gradle resuelve las propiedades en el siguiente orden de prioridad:

  1. gradle.properties a nivel del proyecto (ubicado en la raíz del proyecto).
  2. gradle.properties a nivel de usuario (en el directorio definido por GRADLE_USER_HOME, usualmente ~/.gradle).
  3. gradle.properties en la instalación de Gradle (GRADLE_HOME).

Esto significa que cualquier propiedad definida a nivel de proyecto sobrescribirá la misma propiedad definida a nivel de usuario o instalación. Este orden permite definir valores predeterminados globales y luego sobreescribirlos localmente según sea necesario.

📜 build.gradle.kts​

En el archivo build.gradle.kts, usamos las propiedades definidas en gradle.properties para establecer el grupo y la versión del proyecto. También aplicamos el plugin de convenciones que encapsula la configuración común para todos los módulos.

build.gradle.kts
plugins {
    id("jvm.conventions") // Aplica el plugin de convenciones para JVM
}

val projectGroup = project.findProperty("echo.group")?.toString()
    ?: error("The property 'echo.group' is not defined in gradle.properties")
val projectVersion = libs.versions.echo.get()

allprojects {
    group = projectGroup
    version = projectVersion
}
¿Qué acabamos de hacer?
  • Aplicación del plugin de convenciones: La línea id("jvm.conventions") aplica el plugin que contiene configuraciones comunes para proyectos basados en la JVM. Esto ayuda a centralizar y reutilizar comportamientos entre todos los módulos.
  • Obtener el grupo del proyecto: project.findProperty("echo.group")?.toString() para intentar obtener el valor de la propiedad echo.group definida en gradle.properties. Esta función devuelve null si la propiedad no está definida, por lo que añadimos ?: error(...) para lanzar una excepción en caso de que falte. Esto permite realizar una validación temprana y evitar errores silenciosos durante la compilación.
  • Obtener la versión del proyecto: Se utiliza libs.versions.echo.get() para extraer la versión del proyecto desde el catálogo de versiones (libs.versions.toml). Esto garantiza consistencia en todos los módulos que dependan de esta información.
  • Aplicar configuración a todos los subproyectos: El bloque allprojects { ... } asegura que tanto el grupo como la versión definidos se apliquen a todos los submódulos del proyecto. Esto es especialmente útil en entornos multi-módulo para mantener una configuración coherente y centralizada.

🎯 Conclusiones​

En esta lección exploramos cómo establecer configuraciones globales reutilizables en proyectos Gradle. Vimos cómo aprovechar gradle.properties para definir parámetros importantes como el grupo del proyecto, opciones de rendimiento y configuraciones de la JVM, y cómo referenciar esas propiedades desde build.gradle.kts para aplicarlas de forma centralizada.

Este enfoque no solo facilita el mantenimiento y la legibilidad del proyecto, sino que también ayuda a preparar una base sólida y coherente para escalar hacia proyectos con múltiples módulos y flujos de publicación automatizados.

🔑 Puntos clave​

  • gradle.properties permite definir propiedades globales reutilizables que pueden ser accedidas desde cualquier archivo de construcción del proyecto.
  • El grupo del proyecto se utiliza como parte del identificador del artefacto y suele seguir la convención de dominio invertido (cl.ravenhill, com.github.usuario).
  • Propiedades como org.gradle.caching, org.gradle.parallel y org.gradle.daemon mejoran significativamente el rendimiento de Gradle.
  • Es importante validar explícitamente la existencia de propiedades críticas con findProperty(...) ?: error(...), para evitar errores silenciosos.
  • El uso de allprojects { ... } asegura que la configuración global se aplique a todos los submódulos del proyecto.

🧰 ¿Qué nos llevamos?​

Definir propiedades globales puede parecer un detalle menor al comienzo de un proyecto, pero es una decisión que rinde frutos a medida que este crece. Al centralizar configuraciones como el grupo del proyecto o los parámetros de ejecución de Gradle, no solo ganamos en claridad y orden, sino que sentamos las bases para construir un sistema más coherente, mantenible y fácil de escalar.

Lo que aprendiste en esta sección no es solo una cuestión de sintaxis o archivos de configuración: es una manera de pensar en tu proyecto como un todo, donde cada módulo sigue reglas comunes, cada decisión de diseño se documenta en la estructura misma del proyecto, y donde la automatización empieza desde lo más básico. Esta forma de trabajar te permitirá abordar con más confianza los desafíos que vienen, como la modularización, el versionado o la publicación de artefactos.

📖 Referencias​

🔥 Recomendadas​