settings.gradle : définition, inclusion de modules et pluginManagement

Qu'est-ce que settings.gradle ?

settings.gradle (ou settings.gradle.kts pour Kotlin DSL) est un fichier que Gradle exécute pendant la phase d'Initialization. Il définit la hiérarchie du projet, inclut les modules et configure les dépôts pour les plugins et les dépendances. Sans settings.gradle, Gradle ne sait pas quels modules compiler ni quels plugins sont disponibles. Dans un projet monomodule, settings.gradle peut être absent — Gradle utilise les valeurs par défaut, mais il est obligatoire pour les projets multimodules.

Le fichier settings.gradle se trouve à la racine du projet, à côté du build.gradle racine. Une structure racine typique : settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle est exécuté avant build.gradle — pendant la phase d'Initialization, Gradle construit l'arborescence du projet (Project dans l'API Gradle). Après l'Initialization, la Configuration commence — l'exécution du build.gradle de chaque module.

Historiquement, settings.gradle est apparu dans Gradle 0.7 (2010) et ne contenait initialement que des directives include. Avec l'évolution de Gradle, pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) et versionCatalogs (Gradle 7.4) ont été ajoutés. Le settings.gradle moderne est un fichier de configuration puissant qui centralise la gestion des plugins, des dépôts et des versions pour l'ensemble du projet. Google impose ces capacités dans l'Android Gradle Plugin à partir d'AGP 8.0.

settings.gradle vs build.gradle

settings.gradle gère la structure du projet et les paramètres globaux (plugins, dépôts). build.gradle gère la compilation (dépendances, configurations Android, tâches). settings.gradle est exécuté en premier et a accès à l'API Settings. build.gradle est exécuté ensuite et a accès à l'API Project. Aucune configuration au niveau module (bloc android, dependencies) ne peut être dans settings.gradle — ce serait une erreur.

Inclusion de modules via include

La directive include est le cœur de settings.gradle. Elle indique à Gradle quels modules doivent participer à la compilation. L'argument de include est une chaîne avec le chemin du module : include(":app") inclut un module à la racine, include(":core:network") inclut un module dans le sous-répertoire core/network/. Les deux-points au début indiquent que le chemin est relatif à la racine du projet. Après include, Gradle trouve automatiquement build.gradle dans le répertoire spécifié et ajoute le module à l'arborescence du projet.

Chaque include crée un Project dans l'API Gradle dont le nom est égal à la chaîne include. Le nom du projet est utilisé dans implementation(project(":module")) dans les build.gradle des autres modules. Si un module n'est pas inclus via include, y faire référence depuis un autre module provoquera une erreur « Project not found ». Android Studio IDE utilise également settings.gradle pour afficher les modules dans le panneau Project — les modules sans include ne sont pas visibles dans l'arborescence des fichiers.

include prend en charge les included builds et les composite builds via includeBuild("../library-project"). Cela permet d'inclure des projets Gradle entiers en tant que modules externes. Les included builds sont utiles pour développer des bibliothèques en parallèle avec l'application : les modifications dans la bibliothèque sont immédiatement visibles dans l'application sans publication dans un dépôt Maven. Dans une compilation de production, includeBuild est remplacé par une dépendance Maven normale.

// settings.gradle.kts — structure typique
rootProject.name = "MyApp"

// Modules de l'application
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Inclusion d'une bibliothèque externe (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Bloc de gestion des plugins

Stratégie de résolution

pluginManagement est un bloc dans settings.gradle qui détermine d'où charger les plugins Gradle. Il est apparu dans Gradle 6.8 pour la gestion centralisée des plugins avant leur application. À l'intérieur de pluginManagement se trouvent : repositories (liste des dépôts pour trouver les plugins), resolutionStrategy (règles de résolution des versions) et plugins (déclaration explicite des versions de plugins). Si pluginManagement n'est pas défini, Gradle utilise les dépôts de build.gradle — mais les plugins ne sont recherchés qu'après leur déclaration, ce qui entraîne des erreurs si un plugin n'est pas trouvé.

Dans les projets Android, pluginManagement est obligatoire si des Version Catalogs ou des Convention Plugins sont utilisés. Sans pluginManagement, Gradle ne peut pas trouver le plugin com.android.application lors de son application dans build.gradle.kts. Une configuration typique : repositories contient google() (plugins Android), mavenCentral() (plugins tiers) et gradlePluginPortal() (plugins officiels Gradle).

pluginManagement prend également en charge plugins — la déclaration de plugins avec des versions qui sont ensuite appliquées dans build.gradle sans spécifier la version. Cela centralise les versions des plugins : si 10 modules appliquent kotlin-android, la version est spécifiée une fois dans pluginManagement. Important : pluginManagement.plugins n'est qu'une déclaration. Le plugin lui-même est appliqué dans build.gradle via plugins { id("org.jetbrains.kotlin.android") }.

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

    // Versions des plugins — centralisées
    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 {
        // Version forcée du plugin pour tous les modules
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Application des plugins — apply false (ne pas appliquer à la racine)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Gestion de la résolution des dépendances

Modes de repositoriesMode

dependencyResolutionManagement est un bloc dans settings.gradle qui gère centralisé les dépôts pour tous les modules. Il est apparu dans Gradle 7.0 comme alternative à la déclaration de repositories dans chaque build.gradle. À l'intérieur du bloc sont définis repositoriesMode (mode : PREFER_PROJECT, PREFER_SETTINGS ou FAIL_ON_PROJECT_REPOS) et repositories (liste des dépôts). Si repositoriesMode = PREFER_SETTINGS, les repositories des modules sont ignorés — seule la liste centralisée est utilisée.

repositoriesMode peut prendre trois valeurs. PREFER_SETTINGS — les dépôts de build.gradle sont ignorés, seuls ceux de settings.gradle sont utilisés. PREFER_PROJECT — les dépôts de build.gradle ont priorité sur ceux de settings.gradle. FAIL_ON_PROJECT_REPOS — si un module déclare ses propres dépôts, Gradle génère une erreur. Pour les nouveaux projets, PREFER_SETTINGS est recommandé — il garantit que tous les modules utilisent les mêmes dépôts et élimine la duplication.

repositoriesMode = FAIL_ON_PROJECT_REPOS est particulièrement utile en équipe : si un développeur ajoute un dépôt à un seul module et que les autres ne le voient pas, cela crée le problème « works on my machine ». FAIL_ON_PROJECT_REPOS force tous les dépôts à être déclarés centralisé dans settings.gradle, évitant ces situations. Google recommande FAIL_ON_PROJECT_REPOS pour tous les projets Android à partir d'AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — tous les dépôts ici uniquement
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Dépôt Maven privé
        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") ?: ""
            }
        }
    }
}

// Dans build.gradle du module, repositories ne sont plus nécessaires !
// Tous les dépôts centralisés dans settings.gradle

Catalogues de versions dans settings.gradle

Version Catalogs est une manière centralisée de gérer les versions des dépendances via un fichier TOML. À partir de Gradle 7.4, les catalogues de versions sont le mécanisme recommandé pour tous les projets Android. Le fichier gradle/libs.versions.toml contient trois sections : [versions] (versions), [libraries] (dépendances), [plugins] (plugins). Dans settings.gradle, le catalogue de versions est connecté via @Suppress("UnstableApiUsage") et enableFeaturePreview("VERSION_CATALOGS") (dans les anciennes versions de Gradle).

Après la connexion du catalogue de versions, les dépendances des modules dans build.gradle sont spécifiées via libs : implementation(libs.retrofit). L'IDE fournit l'autocomplétion pour libs. Le catalogue génère automatiquement des accesseurs type-safe : libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Les Bundles sont des groupes de dépendances qui peuvent être inclus en une seule ligne. Les catalogues de versions prennent également en charge l'héritage — plusieurs fichiers TOML peuvent être connectés.

Avantages des catalogues de versions : emplacement unique pour les versions (pas besoin de chercher dans tous les build.gradle) ; accès type-safe (une erreur dans le nom libs est détectée à la compilation, pas à l'exécution) ; mises à jour automatiques (Dependabot et Renovate supportent TOML) ; compatibilité avec les Convention Plugins. Google Firebase et AndroidX distribuent leurs propres catalogues TOML. Pour migrer vers les catalogues de versions, il existe des plugins qui transfèrent automatiquement les versions de build.gradle vers 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" }

Paramètres avancés : includeBuild et fonctionnalités d'incubation

includeBuild est une directive pour créer un composite build : inclure un projet Gradle externe dans le cadre de la compilation actuelle. Contrairement à include (qui inclut un module), includeBuild inclut un projet complet avec son propre settings.gradle, ses modules et ses plugins. Les composite builds sont utilisés pour : développer des bibliothèques (analytique, réseau) en parallèle avec l'application ; inclure des Convention Plugins depuis un dépôt séparé ; intégrer des modules build-logic.

Fonctionnalités d'incubation (Incubating Features) sont des options expérimentales de Gradle qui sont activées via enableFeaturePreview("FEATURE_NAME"). Dans AGP 8.7+, sont disponibles : TYPESAFE_PROJECT_ACCESSORS (accès type-safe aux projets dans un projet multimodule : au lieu de project(":core:network"), on peut écrire projects.core.network), STABLE_CONFIGURATION_CACHE (mise en cache stable de la configuration), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformation d'artefacts). Les fonctionnalités d'incubation peuvent être activées en production, mais l'API peut changer dans les versions futures.

Gradle Enterprise et Build Scan sont également configurés via settings.gradle : plugins { id("com.gradle.enterprise") } avec un bloc gradleEnterprise. Build Scan est un service cloud qui affiche des informations détaillées sur chaque compilation : temps d'exécution de chaque tâche, mise en cache, erreurs. L'activation de Build Scan aide à diagnostiquer les problèmes de vitesse de compilation. Build Scan est gratuit pour les projets open source.

// Fonctionnalités d'incubation
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)
    }
}

// Utilisation des accesseurs type-safe de projet dans build.gradle
// Au lieu de : implementation(project(":core:network"))
// On peut : implementation(projects.core.network)