settings.gradle: qué es, include de módulos y pluginManagement

¿Qué es settings.gradle?

settings.gradle (o settings.gradle.kts para Kotlin DSL) es un archivo que Gradle ejecuta durante la fase de Initialization. En él se define la jerarquía del proyecto, se incluyen módulos y se configuran repositorios para plugins y dependencias. Sin settings.gradle, Gradle no sabe qué módulos compilar ni qué plugins están disponibles. En un proyecto de un solo módulo, settings.gradle puede estar ausente — Gradle usa valores predeterminados, pero es obligatorio para proyectos multimódulo.

El archivo settings.gradle se encuentra en la raíz del proyecto, junto con build.gradle raíz. Una estructura típica de la raíz del proyecto: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle se ejecuta antes que build.gradle — durante la fase de Initialization, Gradle construye el árbol del proyecto (Project en la API de Gradle). Después de Initialization, comienza Configuration — la ejecución del build.gradle de cada módulo.

Históricamente, settings.gradle apareció en Gradle 0.7 (2010) y originalmente solo contenía directivas include. Con la evolución de Gradle, se añadieron pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) y versionCatalogs (Gradle 7.4). El settings.gradle moderno es un potente archivo de configuración que centraliza la gestión de plugins, repositorios y versiones para todo el proyecto. Google refuerza estas capacidades en Android Gradle Plugin a partir de AGP 8.0.

settings.gradle vs build.gradle

settings.gradle gestiona la estructura del proyecto y la configuración global (plugins, repositorios). build.gradle gestiona la compilación (dependencias, configuraciones de Android, tareas). settings.gradle se ejecuta primero y tiene acceso a la API de Settings. build.gradle se ejecuta después y tiene acceso a la API de Project. Ninguna configuración a nivel de módulo (bloque android, dependencies) puede estar en settings.gradle — eso sería un error.

Inclusión de módulos mediante include

La directiva include es el núcleo de settings.gradle. Indica a Gradle qué módulos deben participar en la compilación. El argumento de include es una cadena con la ruta del módulo: include(":app") incluye un módulo en la raíz, include(":core:network") incluye un módulo en el subdirectorio core/network/. Los dos puntos al inicio indican que la ruta es relativa a la raíz del proyecto. Después de include, Gradle encuentra automáticamente build.gradle en el directorio especificado y añade el módulo al árbol del proyecto.

Cada include crea un Project en la API de Gradle con el nombre igual a la cadena de include. El nombre del proyecto se usa en implementation(project(":module")) en los build.gradle de otros módulos. Si un módulo no está incluido mediante include, referenciarlo desde otro módulo provocará un error “Project not found”. Android Studio también usa settings.gradle para mostrar los módulos en el panel Project — los módulos sin include no son visibles en el árbol de archivos.

include admite included builds y composite builds mediante includeBuild("../library-project"). Esto permite incluir proyectos Gradle completos como módulos externos. Los included builds son útiles para desarrollar librerías en paralelo con la aplicación: los cambios en la librería se ven inmediatamente en la aplicación sin necesidad de publicar en un repositorio Maven. En una compilación de producción, includeBuild se reemplaza por una dependencia Maven normal.

// settings.gradle.kts — estructura típica
rootProject.name = "MyApp"

// Módulos de la aplicación
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Inclusión de una librería externa (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Plugin Management Block

Estrategia de resolución

pluginManagement es un bloque en settings.gradle que determina de dónde cargar los plugins de Gradle. Apareció en Gradle 6.8 para la gestión centralizada de plugins antes de su aplicación. Dentro de pluginManagement se encuentran: repositories (lista de repositorios para buscar plugins), resolutionStrategy (reglas de resolución de versiones) y plugins (declaración explícita de versiones de plugins). Si no se define pluginManagement, Gradle usa los repositorios de build.gradle — pero los plugins se buscan solo después de declararse, lo que provoca errores si no se encuentra un plugin.

En proyectos Android, pluginManagement es obligatorio si se usan Version Catalogs o Convention Plugins. Sin pluginManagement, Gradle no puede encontrar el plugin com.android.application al aplicarlo en build.gradle.kts. Una configuración típica: repositories contiene google() (plugins de Android), mavenCentral() (plugins de terceros) y gradlePluginPortal() (plugins oficiales de Gradle).

pluginManagement también admite plugins — declarar plugins con versiones que luego se aplican en build.gradle sin especificar la versión. Esto centraliza las versiones de plugins: si 10 módulos aplican kotlin-android, la versión se especifica una vez en pluginManagement. Importante: pluginManagement.plugins es solo una declaración. El plugin se aplica en build.gradle mediante plugins { id("org.jetbrains.kotlin.android") }.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = "https://jitpack.io" }
    }

    // Versiones de plugins — centralizadas
    plugins {
        id("com.android.application") version "8.7.0"
        id("com.android.library") version "8.7.0"
        id("org.jetbrains.kotlin.android") version "2.0.21"
        id("com.google.devtools.ksp") version "2.0.21-1.0.25"
    }

    resolutionStrategy {
        // Versión forzada de plugin para todos los módulos
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Aplicación de plugins — apply false (no aplicar a la raíz)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

Modos de repositoriesMode

dependencyResolutionManagement es un bloque en settings.gradle que gestiona centralizadamente los repositorios para todos los módulos. Apareció en Gradle 7.0 como alternativa a declarar repositories en cada build.gradle. Dentro del bloque se definen repositoriesMode (modo: PREFER_PROJECT, PREFER_SETTINGS o FAIL_ON_PROJECT_REPOS) y repositories (lista de repositorios). Si repositoriesMode = PREFER_SETTINGS, los repositories de los módulos se ignoran — solo se usa la lista centralizada.

repositoriesMode puede tomar tres valores. PREFER_SETTINGS — los repositorios de build.gradle se ignoran, solo se usan los de settings.gradle. PREFER_PROJECT — los repositorios de build.gradle tienen prioridad sobre settings.gradle. FAIL_ON_PROJECT_REPOS — si un módulo declara sus propios repositorios, Gradle lanza un error. Para proyectos nuevos, se recomienda PREFER_SETTINGS — garantiza que todos los módulos usen los mismos repositorios y elimina la duplicación.

repositoriesMode = FAIL_ON_PROJECT_REPOS es especialmente útil en equipos: si un desarrollador añade un repositorio a un solo módulo y los demás no lo ven, se produce el problema “works on my machine”. FAIL_ON_PROJECT_REPOS obliga a declarar todos los repositorios centralizadamente en settings.gradle, evitando estas situaciones. Google recomienda FAIL_ON_PROJECT_REPOS para todos los proyectos Android a partir de AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — todos los repositorios solo aquí
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

    repositories {
        google()
        mavenCentral()
        maven { url = "https://jitpack.io" }

        // Repositorio Maven privado
        maven {
            url = "https://maven.pkg.github.com/company/internal-lib"
            credentials {
                username = providers.gradleProperty("gpr.user")
                    .getOrNull() ?: System.getenv("GPR_USER") ?: ""
                password = providers.gradleProperty("gpr.key")
                    .getOrNull() ?: System.getenv("GPR_KEY") ?: ""
            }
        }
    }
}

// ¡En build.gradle del módulo ya no se necesitan repositories!
// Todos los repositorios centralizados en settings.gradle

Version Catalogs en settings.gradle

Version Catalogs es una forma centralizada de gestionar las versiones de dependencias mediante un archivo TOML. A partir de Gradle 7.4, Version Catalogs es el mecanismo recomendado para todos los proyectos Android. El archivo gradle/libs.versions.toml contiene tres secciones: [versions] (versiones), [libraries] (dependencias), [plugins] (plugins). En settings.gradle, el Version Catalog se conecta mediante @Suppress("UnstableApiUsage") y enableFeaturePreview("VERSION_CATALOGS") (en versiones antiguas de Gradle).

Después de conectar el Version Catalog, las dependencias de los módulos en build.gradle se especifican mediante libs: implementation(libs.retrofit). El IDE proporciona autocompletado para libs. El catálogo genera automáticamente accessors type-safe: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Los Bundles son grupos de dependencias que se pueden incluir con una sola línea. Version Catalogs también admite herencia — se pueden conectar varios archivos TOML.

Ventajas de Version Catalogs: un único lugar para las versiones (no hay que buscar en todos los build.gradle); acceso type-safe (un error en el nombre de libs se detecta en compilación, no en ejecución); actualizaciones automáticas (Dependabot y Renovate soportan TOML); compatibilidad con Convention Plugins. Google Firebase y AndroidX distribuyen sus propios catálogos TOML. Para migrar a Version Catalogs, existen plugins que transfieren automáticamente las versiones de build.gradle a TOML.

# gradle/libs.versions.toml
[versions]
agp = "8.7.0"
kotlin = "2.0.21"
composeBom = "2024.12.01"
retrofit = "2.11.0"
coroutines = "1.9.0"

[libraries]
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }
kotlin-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }
compose-ui = { module = "androidx.compose.ui:ui" }

[bundles]
compose = ["compose-ui", "compose-material3"]

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

Ajustes avanzados: includeBuild y características incipientes

includeBuild es una directiva para crear un composite build: incluir un proyecto Gradle externo como parte de la compilación actual. A diferencia de include (que incluye un módulo), includeBuild incluye un proyecto completo con su propio settings.gradle, módulos y plugins. Los composite builds se usan para: desarrollar librerías (analítica, red) en paralelo con la aplicación; incluir Convention Plugins desde un repositorio separado; integrar módulos build-logic.

Características incipientes (Incubating Features) son opciones experimentales de Gradle que se activan mediante enableFeaturePreview("FEATURE_NAME"). En AGP 8.7+, están disponibles: TYPESAFE_PROJECT_ACCESSORS (acceso type-safe a proyectos en un proyecto multimódulo: en lugar de project(":core:network"), se puede escribir projects.core.network), STABLE_CONFIGURATION_CACHE (caché de configuración estable), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformación de artefactos). Las características incipientes pueden activarse en producción, pero la API puede cambiar en versiones futuras.

Gradle Enterprise y Build Scan también se configuran mediante settings.gradle: plugins { id("com.gradle.enterprise") } con un bloque gradleEnterprise. Build Scan es un servicio en la nube que muestra información detallada de cada compilación: tiempo de ejecución de cada tarea, almacenamiento en caché, errores. Activar Build Scan ayuda a diagnosticar problemas de velocidad de compilación. Build Scan es gratuito para proyectos de código abierto.

// Características incipientes
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
enableFeaturePreview("STABLE_CONFIGURATION_CACHE")

// Gradle Enterprise / Build Scan
plugins {
    id("com.gradle.enterprise") version "3.18"
}

gradleEnterprise {
    buildScan {
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        publishAlwaysIf(true)
    }
}

// Uso de type-safe project accessors en build.gradle
// En lugar de: implementation(project(":core:network"))
// Se puede: implementation(projects.core.network)