settings.gradle: modules toevoegen en pluginManagement

Wat is settings.gradle?

settings.gradle (of settings.gradle.kts voor Kotlin DSL) is het bestand dat Gradle uitvoert in de Initialization-fase. Het definieert de projecthiërarchie, voegt modules toe en configureert repositories voor plug-ins en afhankelijkheden. Zonder settings.gradle weet Gradle niet welke modules te bouwen en welke plug-ins beschikbaar zijn. In een project met één module kan settings.gradle ontbreken — Gradle gebruikt standaardwaarden, maar voor multimodale projecten is het verplicht.

Het settings.gradle-bestand bevindt zich in de projectroot, naast de root build.gradle. Typische structuur van de projectroot: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle wordt uitgevoerd vóór build.gradle — in de Initialization-fase bouwt Gradle de projectboom (Project in de Gradle API). Na Initialization begint de Configuration — uitvoering van build.gradle van elke module.

Historisch gezien verscheen settings.gradle in Gradle 0.7 (2010) en bevatte oorspronkelijk alleen include-richtlijnen. Met de ontwikkeling van Gradle werden pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) en versionCatalogs (Gradle 7.4) toegevoegd aan settings.gradle. Modern settings.gradle is een krachtig configuratiebestand dat het beheer van plug-ins, repositories en versies voor het hele project centraliseert. Google verankert deze mogelijkheden in de Android Gradle Plugin vanaf AGP 8.0.

settings.gradle vs build.gradle

settings.gradle beheert de projectstructuur en globale instellingen (plug-ins, repositories). build.gradle beheert de build (afhankelijkheden, Android-configuraties, taken). settings.gradle wordt eerst uitgevoerd en heeft toegang tot de Settings API. build.gradle wordt later uitgevoerd en heeft toegang tot de Project API. Geen enkele moduleconfiguratie (android-blok, dependencies) mag in settings.gradle staan — dat is een fout.

Modules toevoegen via include

De include-richtlijn is de primaire richtlijn in settings.gradle. Het vertelt Gradle welke modules aan de build moeten deelnemen. Het argument van include is het modulepad: include(":app") — voegt een module in de root toe, include(":core:network") — een module in de submap core/network/. De dubbele punt aan het begin geeft aan dat het pad relatief is ten opzichte van de projectroot. Na include vindt Gradle automatisch build.gradle in de opgegeven map en voegt de module toe aan de projectboom.

Elke include creëert een Project in de Gradle API met een naam gelijk aan de include-string. De projectnaam wordt gebruikt in implementation(project(":module")) in build.gradle van andere modules. Als een module niet via include is toegevoegd, zal een verwijzing ernaar vanuit een andere module een fout "Project not found" veroorzaken. Android Studio IDE gebruikt ook settings.gradle voor het weergeven van modules in het Project-paneel — modules zonder include zijn niet zichtbaar in de bestandsboom.

include ondersteunt included builds en composite builds via includeBuild("../library-project"). Dit maakt het mogelijk om volledige Gradle-projecten als externe modules toe te voegen. Included builds zijn handig voor parallelle ontwikkeling van bibliotheken met de applicatie: wijzigingen in de bibliotheek zijn direct zichtbaar in de applicatie zonder publicatie naar een maven-repository. In een productiebuild wordt includeBuild vervangen door een gewone maven-afhankelijkheid.

// settings.gradle.kts — typische structuur
rootProject.name = "MyApp"

// Applicatiemodules
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Externe bibliotheek toevoegen (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Plugin Management-blok

Resolution Strategy

pluginManagement — een blok in settings.gradle dat bepaalt waar Gradle-plug-ins vandaan worden geladen. Verschenen in Gradle 6.8 voor gecentraliseerd beheer van plug-ins voordat ze worden toegepast. Binnen pluginManagement bevinden zich: repositories (lijst van repositories voor het zoeken naar plug-ins), resolutionStrategy (regels voor versieresolutie) en plugins (expliciete vermelding van pluginversies). Als pluginManagement niet is ingesteld, gebruikt Gradle de repositories uit build.gradle — maar plug-ins worden pas gezocht nadat ze zijn gedeclareerd, wat leidt tot fouten als een plug-in niet wordt gevonden.

In een Android-project is pluginManagement verplicht als Versiecatalogi of Convention Plugins worden gebruikt. Zonder pluginManagement kan Gradle de plug-in com.android.application niet vinden bij toepassing in build.gradle.kts. Typische configuratie: repositories bevat google() (Android-plug-ins), mavenCentral() (third-party plug-ins) en gradlePluginPortal() (officiële Gradle-plug-ins).

pluginManagement ondersteunt ook plugins — declaratie van plug-ins met versies die vervolgens in build.gradle worden toegepast zonder versievermelding. Dit centraliseert pluginversies: als 10 modules kotlin-android toepassen, wordt de versie één keer in pluginManagement vermeld. Belangrijk: pluginManagement.plugins is alleen een declaratie. De plug-in zelf wordt toegepast in build.gradle via plugins { id("org.jetbrains.kotlin.android") }.

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

    // Pluginversies — gecentraliseerd
    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 {
        // Geforceerde pluginversie voor alle modules
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Plug-ins toepassen — apply false (niet toepassen op root)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

repositoriesMode-modus

dependencyResolutionManagement — een blok in settings.gradle dat gecentraliseerd repositories beheert voor alle modules. Verschenen in Gradle 7.0 als alternatief voor het declareren van repositories in elke build.gradle. Binnen het blok worden repositoriesMode (modus: PREFER_PROJECT, PREFER_SETTINGS of FAIL_ON_PROJECT_REPOS) en repositories (lijst van repositories) ingesteld. Als repositoriesMode = PREFER_SETTINGS, worden module-repositories genegeerd — alleen de gecentraliseerde lijst wordt gebruikt.

repositoriesMode kan drie waarden aannemen. PREFER_SETTINGS — repositories uit build.gradle worden genegeerd, alleen die uit settings.gradle worden gebruikt. PREFER_PROJECT — build.gradle-repositories hebben prioriteit boven settings.gradle. FAIL_ON_PROJECT_REPOS — als een module eigen repositories declareert, geeft Gradle een foutmelding. Voor nieuwe projecten wordt PREFER_SETTINGS aanbevolen — dit garandeert dat alle modules dezelfde repositories gebruiken en elimineert duplicatie.

repositoriesMode = FAIL_ON_PROJECT_REPOS is vooral handig in teams: als een ontwikkelaar een repository slechts aan één module toevoegt en de anderen deze niet zien, ontstaat de situatie "works on my machine". FAIL_ON_PROJECT_REPOS dwingt af dat alle repositories gecentraliseerd in settings.gradle worden gedeclareerd, wat dergelijke situaties voorkomt. Google beveelt FAIL_ON_PROJECT_REPOS aan voor alle Android-projecten vanaf AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — alle repositories alleen hier
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Privé-maven-repository
        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") ?: ""
            }
        }
    }
}

// In build.gradle van de module zijn repositories niet meer nodig!
// Alle repositories gecentraliseerd in settings.gradle

Versiecatalogi in settings.gradle

Versiecatalogi zijn een gecentraliseerde manier om afhankelijkheidsversies te beheren via een TOML-bestand. Vanaf Gradle 7.4 zijn Versiecatalogi het aanbevolen mechanisme voor alle Android-projecten. Het bestand gradle/libs.versions.toml bevat drie secties: [versions] (versies), [libraries] (afhankelijkheden), [plugins] (plug-ins). In settings.gradle wordt de Versiecatalogus toegevoegd via @Suppress("UnstableApiUsage") en enableFeaturePreview("VERSION_CATALOGS") (in oudere Gradle-versies).

Na het toevoegen van de Versiecatalogus worden afhankelijkheden in build.gradle van modules gespecificeerd via libs: implementation(libs.retrofit). De IDE biedt automatische aanvulling voor libs. De catalogus genereert automatisch type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles zijn groepen afhankelijkheden die met één regel kunnen worden toegevoegd. Versiecatalogi ondersteunen ook overerving — meerdere TOML-bestanden kunnen worden toegevoegd.

Voordelen van Versiecatalogi: één plek voor versies (niet zoeken in alle build.gradle); type-safe toegang (fout in libs-naam wordt gedetecteerd in de compilatiefase, niet in runtime); automatische updates (Dependabot en Renovate ondersteunen TOML); compatibiliteit met Convention Plugins. Google Firebase en AndroidX distribueren hun eigen TOML-catalogi. Voor migratie naar Versiecatalogi bestaan plug-ins die automatisch versies van build.gradle naar TOML verplaatsen.

# 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" }

Geavanceerde instellingen: includeBuild en experimentele functies

includeBuild is een richtlijn voor het maken van een composite build: het toevoegen van een extern Gradle-project als onderdeel van de huidige build. In tegenstelling tot include (voegt een module toe), voegt includeBuild een volledig project toe met eigen settings.gradle, modules en plug-ins. Composite builds worden gebruikt voor: parallelle ontwikkeling van bibliotheken (analytics, netwerk) met de applicatie; toevoegen van Convention Plugins uit een aparte repository; integratie van de build-logic-module.

Experimentele functies (Incubating Features) — experimentele Gradle-opties die worden ingeschakeld via enableFeaturePreview("FEATURE_NAME"). In AGP 8.7+ zijn beschikbaar: TYPESAFE_PROJECT_ACCESSORS (type-safe toegang tot projecten in een multimodulair project: in plaats van project(":core:network") kan men projects.core.network schrijven), STABLE_CONFIGURATION_CACHE (stabiele configuratiecache), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (artefacttransformatie). Experimentele functies kunnen in productie worden ingeschakeld, maar de API kan in toekomstige versies veranderen.

Gradle Enterprise en Build Scan worden ook geconfigureerd via settings.gradle: plugins { id("com.gradle.enterprise") } met een gradleEnterprise-blok. Build Scan is een cloudservice die gedetailleerde informatie over elke build toont: uitvoeringstijd van elke taak, caching, fouten. Het inschakelen van Build Scan helpt bij het diagnosticeren van problemen met de buildsnelheid. Voor opensource-projecten is Build Scan gratis.

// Experimentele functies
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)
    }
}

// Gebruik van type-safe project accessors in build.gradle
// In plaats van: implementation(project(":core:network"))
// Kan: implementation(projects.core.network)