settings.gradle: Was es ist, Module einbinden und pluginManagement

Was ist settings.gradle?

settings.gradle (oder settings.gradle.kts für Kotlin DSL) ist eine Datei, die Gradle während der Initialisierungsphase ausführt. Sie definiert die Projekthierarchie, bindet Module ein und konfiguriert Repositories für Plugins und Abhängigkeiten. Ohne settings.gradle weiß Gradle nicht, welche Module zu bauen sind und welche Plugins verfügbar sind. In einem Einmodulprojekt kann settings.gradle fehlen – Gradle verwendet Standardwerte, aber für Multimodulprojekte ist es erforderlich.

Die settings.gradle-Datei befindet sich im Projektstammverzeichnis neben der Stamm-build.gradle. Eine typische Stammprojektstruktur: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle wird vor build.gradle ausgeführt – während der Initialisierungsphase erstellt Gradle den Projektbaum (Project in der Gradle-API). Nach Abschluss der Initialisierung beginnt die Konfiguration – die Ausführung der build.gradle jedes Moduls.

Historisch gesehen erschien settings.gradle in Gradle 0.7 (2010) und enthielt zunächst nur include-Direktiven. Mit der Weiterentwicklung von Gradle kamen pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) und versionCatalogs (Gradle 7.4) hinzu. Modernes settings.gradle ist eine leistungsstarke Konfigurationsdatei, die die Plugin-, Repository- und Versionsverwaltung für das gesamte Projekt zentralisiert. Google schreibt diese Fähigkeiten ab AGP 8.0 im Android Gradle Plugin vor.

settings.gradle vs. build.gradle

settings.gradle verwaltet die Projektstruktur und globale Einstellungen (Plugins, Repositories). build.gradle verwaltet den Build (Abhängigkeiten, Android-Konfigurationen, Aufgaben). settings.gradle wird zuerst ausgeführt und hat Zugriff auf die Settings-API. build.gradle wird danach ausgeführt und hat Zugriff auf die Project-API. Keine Modulebene-Konfigurationen (android-Block, dependencies) können in settings.gradle stehen – das wäre ein Fehler.

Module über include einbinden

Die include-Direktive ist der Kern von settings.gradle. Sie teilt Gradle mit, welche Module am Build teilnehmen sollen. Das Argument von include ist ein String mit dem Modulpfad: include(":app") bindet ein Modul auf Stammebene ein, include(":core:network") bindet ein Modul im Unterverzeichnis core/network/ ein. Der Doppelpunkt am Anfang zeigt an, dass der Pfad relativ zum Projektstamm ist. Nach include findet Gradle automatisch build.gradle im angegebenen Verzeichnis und fügt das Modul zum Projektbaum hinzu.

Jedes include erstellt ein Project in der Gradle-API mit dem Namen, der dem include-String entspricht. Der Projektname wird in implementation(project(":module")) in den build.gradle-Dateien anderer Module verwendet. Wenn ein Modul nicht über include eingebunden ist, führt ein Verweis darauf aus einem anderen Modul zu einem „Project not found“-Fehler. Android Studio IDE verwendet settings.gradle auch zur Anzeige von Modulen im Projektbereich – Module ohne include sind im Dateibaum nicht sichtbar.

include unterstützt included builds und composite builds über includeBuild("../library-project"). Dies ermöglicht das Einbinden kompletter Gradle-Projekte als externe Module. Included builds sind nützlich für die parallele Entwicklung von Bibliotheken mit der Anwendung: Änderungen an der Bibliothek sind sofort in der Anwendung sichtbar, ohne Veröffentlichung in einem Maven-Repository. In einem Produktionsbuild wird includeBuild durch eine normale Maven-Abhängigkeit ersetzt.

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

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

// Einbinden einer externen Bibliothek (Composite Build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Plugin-Management-Block

Auflösungsstrategie

pluginManagement ist ein Block in settings.gradle, der festlegt, von wo Gradle-Plugins geladen werden. Er wurde in Gradle 6.8 für die zentrale Plugin-Verwaltung vor deren Anwendung eingeführt. Innerhalb von pluginManagement befinden sich: repositories (Liste der Repositories zum Auffinden von Plugins), resolutionStrategy (Versionsauflösungsregeln) und plugins (explizite Plugin-Versionsdeklarationen). Wenn pluginManagement nicht definiert ist, verwendet Gradle die Repositories aus build.gradle – aber Plugins werden erst nach ihrer Deklaration gesucht, was zu Fehlern führt, wenn ein Plugin nicht gefunden wird.

In Android-Projekten ist pluginManagement erforderlich, wenn Version Catalogs oder Convention Plugins verwendet werden. Ohne pluginManagement kann Gradle das Plugin com.android.application bei der Anwendung in build.gradle.kts nicht finden. Eine typische Konfiguration: repositories enthält google() (Android-Plugins), mavenCentral() (Drittanbieter-Plugins) und gradlePluginPortal() (offizielle Gradle-Plugins).

pluginManagement unterstützt auch plugins – die Deklaration von Plugins mit Versionen, die dann in build.gradle ohne Angabe der Version angewendet werden. Dies zentralisiert Plugin-Versionen: Wenn 10 Module kotlin-android anwenden, wird die Version einmal in pluginManagement angegeben. Wichtig: pluginManagement.plugins ist nur eine Deklaration. Das Plugin selbst wird in build.gradle über plugins { id("org.jetbrains.kotlin.android") } angewendet.

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

    // Plugin-Versionen — zentral
    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 {
        // Erzwungene Plugin-Version für alle Module
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Anwenden von Plugins — apply false (nicht auf Stamm anwenden)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Abhängigkeitsauflösungs-Management

repositoriesMode-Modi

dependencyResolutionManagement ist ein Block in settings.gradle, der die Repositories für alle Module zentral verwaltet. Er wurde in Gradle 7.0 als Alternative zur Deklaration von repositories in jeder build.gradle eingeführt. Innerhalb des Blocks werden repositoriesMode (Modus: PREFER_PROJECT, PREFER_SETTINGS oder FAIL_ON_PROJECT_REPOS) und repositories (Liste der Repositories) festgelegt. Wenn repositoriesMode = PREFER_SETTINGS ist, werden moduleigene repositories ignoriert – nur die zentralisierte Liste wird verwendet.

repositoriesMode kann drei Werte annehmen. PREFER_SETTINGS – Repositories aus build.gradle werden ignoriert, nur die aus settings.gradle werden verwendet. PREFER_PROJECT – build.gradle-Repositories haben Vorrang vor settings.gradle. FAIL_ON_PROJECT_REPOS – wenn ein Modul eigene Repositories deklariert, gibt Gradle einen Fehler aus. Für neue Projekte wird PREFER_SETTINGS empfohlen – es stellt sicher, dass alle Module dieselben Repositories verwenden, und beseitigt Duplikate.

repositoriesMode = FAIL_ON_PROJECT_REPOS ist besonders in Teams nützlich: Wenn ein Entwickler ein Repository nur zu einem Modul hinzufügt und andere es nicht sehen, entsteht das „works on my machine“-Problem. FAIL_ON_PROJECT_REPOS erzwingt, dass alle Repositories zentral in settings.gradle deklariert werden, und verhindert solche Situationen. Google empfiehlt FAIL_ON_PROJECT_REPOS für alle Android-Projekte ab AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — alle Repositories nur hier
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Privates 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 des Moduls sind repositories nicht mehr nötig!
// Alle Repositories in settings.gradle zentralisiert

Version Catalogs in settings.gradle

Version Catalogs ist eine zentralisierte Methode zur Verwaltung von Abhängigkeitsversionen über eine TOML-Datei. Ab Gradle 7.4 sind Version Catalogs der empfohlene Mechanismus für alle Android-Projekte. Die Datei gradle/libs.versions.toml enthält drei Abschnitte: [versions] (Versionen), [libraries] (Abhängigkeiten), [plugins] (Plugins). In settings.gradle wird der Version Catalog über @Suppress("UnstableApiUsage") und enableFeaturePreview("VERSION_CATALOGS") (in älteren Gradle-Versionen) eingebunden.

Nach dem Einbinden des Version Catalog werden Modulabhängigkeiten in build.gradle über libs angegeben: implementation(libs.retrofit). Die IDE bietet Autovervollständigung für libs. Der Katalog generiert automatisch typsichere Accessoren: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles sind Gruppen von Abhängigkeiten, die mit einer einzigen Zeile eingebunden werden können. Version Catalogs unterstützen auch Vererbung – mehrere TOML-Dateien können eingebunden werden.

Vorteile von Version Catalogs: Einheitlicher Ort für Versionen (kein Suchen in allen build.gradle-Dateien); typsicherer Zugriff (ein Tippfehler im libs-Namen wird zur Kompilierzeit erkannt, nicht zur Laufzeit); automatische Updates (Dependabot und Renovate unterstützen TOML); Kompatibilität mit Convention Plugins. Google Firebase und AndroidX vertreiben eigene TOML-Kataloge. Für die Migration zu Version Catalogs gibt es Plugins, die Versionen automatisch von build.gradle nach TOML übertragen.

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

Erweiterte Einstellungen: includeBuild und Inkubationsfunktionen

includeBuild ist eine Direktive zum Erstellen eines Composite Builds: Einbinden eines externen Gradle-Projekts als Teil des aktuellen Builds. Anders als include (das ein Modul einbindet) bindet includeBuild ein komplettes Projekt mit eigener settings.gradle, Modulen und Plugins ein. Composite Builds werden verwendet für: parallele Entwicklung von Bibliotheken (Analytik, Netzwerk) mit der Anwendung; Einbinden von Convention Plugins aus einem separaten Repository; Integration von build-logic-Modulen.

Inkubationsfunktionen (Incubating Features) sind experimentelle Gradle-Optionen, die über enableFeaturePreview("FEATURE_NAME") aktiviert werden. In AGP 8.7+ sind verfügbar: TYPESAFE_PROJECT_ACCESSORS (typsicherer Zugriff auf Projekte in einem Multimodulprojekt: statt project(":core:network") kann man projects.core.network schreiben), STABLE_CONFIGURATION_CACHE (stabiles Konfigurations-Caching), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (Artefakttransformation). Inkubationsfunktionen können in der Produktion aktiviert werden, aber die API kann sich in zukünftigen Versionen ändern.

Gradle Enterprise und Build Scan werden ebenfalls über settings.gradle konfiguriert: plugins { id("com.gradle.enterprise") } mit einem gradleEnterprise-Block. Build Scan ist ein Cloud-Dienst, der detaillierte Informationen zu jedem Build anzeigt: Ausführungszeit jeder Aufgabe, Caching, Fehler. Die Aktivierung von Build Scan hilft bei der Diagnose von Build-Geschwindigkeitsproblemen. Build Scan ist für Open-Source-Projekte kostenlos.

// Inkubationsfunktionen
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)
    }
}

// Verwendung von typsicheren Projekt-Accessoren in build.gradle
// Statt: implementation(project(":core:network"))
// Möglich: implementation(projects.core.network)