settings.gradle: inkludera moduler och pluginManagement

Vad är settings.gradle?

settings.gradle (eller settings.gradle.kts för Kotlin DSL) är den fil som Gradle kör i Initialization-fasen. I den definieras projekthierarkin, moduler inkluderas, repositories för plugins och beroenden konfigureras. Utan settings.gradle vet Gradle inte vilka moduler som ska byggas och vilka plugins som är tillgängliga. I ett enmodulsprojekt kan settings.gradle saknas — Gradle använder standardvärden, men för multimodulprojekt är det obligatoriskt.

Filen settings.gradle finns i projektroten, bredvid rotens build.gradle. Typisk struktur för projektroten: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle körs före build.gradle — i Initialization-fasen bygger Gradle projektträdet (Project i Gradle API). Efter Initialization börjar Configuration — körning av varje moduls build.gradle.

Historiskt sett dök settings.gradle upp i Gradle 0.7 (2010) och innehöll från början endast include-direktiv. Med Gradles utveckling lades pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) och versionCatalogs (Gradle 7.4) till i settings.gradle. Modern settings.gradle är en kraftfull konfigurationsfil som centraliserar hanteringen av plugins, repositories och versioner för hela projektet. Google befäster dessa möjligheter i Android Gradle Plugin från och med AGP 8.0.

settings.gradle vs build.gradle

settings.gradle hanterar projektstrukturen och globala inställningar (plugins, repositories). build.gradle hanterar bygget (beroenden, Android-konfigurationer, tasks). settings.gradle körs först och har tillgång till Settings API. build.gradle körs senare och har tillgång till Project API. Inga modulkonfigurationer (android-block, dependencies) får finnas i settings.gradle — det är ett fel.

Inkludera moduler via include

include-direktivet är det primära direktivet i settings.gradle. Det talar om för Gradle vilka moduler som ska delta i bygget. Argumentet för include är modulsökvägen: include(":app") — inkluderar en modul i roten, include(":core:network") — en modul i underkatalogen core/network/. Kolon i början indikerar att sökvägen är relativ till projektroten. Efter include hittar Gradle automatiskt build.gradle i den angivna katalogen och lägger till modulen i projektträdet.

Varje include skapar ett Project i Gradle API med ett namn som är lika med include-strängen. Projektnamnet används i implementation(project(":module")) i andra modulers build.gradle. Om en modul inte är inkluderad via include, kommer en referens till den från en annan modul att orsaka felet "Project not found". Android Studio IDE använder också settings.gradle för att visa moduler i Project-panelen — moduler utan include syns inte i filträdet.

include stöder included builds och composite builds via includeBuild("../library-project"). Detta gör det möjligt att inkludera hela Gradle-projekt som externa moduler. Included builds är användbara för parallell utveckling av bibliotek med applikationen: ändringar i biblioteket syns omedelbart i applikationen utan publicering till ett maven-repository. I produktionsbygget ersätts includeBuild med ett vanligt maven-beroende.

// settings.gradle.kts — typisk struktur
rootProject.name = "MyApp"

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

// Inkludera externt bibliotek (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Plugin Management-block

Resolution Strategy

pluginManagement — ett block i settings.gradle som bestämmer varifrån Gradle-plugins laddas. Dök upp i Gradle 6.8 för centraliserad hantering av plugins innan de tillämpas. Inuti pluginManagement finns: repositories (lista över repositories för sökning av plugins), resolutionStrategy (regler för versionslösning) och plugins (explicit angivelse av pluginversioner). Om pluginManagement inte är inställt använder Gradle repositories från build.gradle — men plugins söks först efter att de deklarerats, vilket leder till fel om en plugin inte hittas.

I ett Android-projekt är pluginManagement obligatoriskt om Versionskataloger eller Convention Plugins används. Utan pluginManagement kan Gradle inte hitta plugin com.android.application vid tillämpning i build.gradle.kts. Typisk konfiguration: repositories innehåller google() (Android-plugins), mavenCentral() (tredjepartsplugins) och gradlePluginPortal() (officiella Gradle-plugins).

pluginManagement stöder också plugins — deklaration av plugins med versioner som sedan tillämpas i build.gradle utan versionsangivelse. Detta centraliserar pluginversioner: om 10 moduler tillämpar kotlin-android anges versionen en gång i pluginManagement. Viktigt: pluginManagement.plugins är endast en deklaration. Själva pluginen tillämpas i build.gradle via plugins { id("org.jetbrains.kotlin.android") }.

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

    // Pluginversioner — centraliserat
    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 {
        // Tvingad pluginversion för alla moduler
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Tillämpa plugins — apply false (tillämpa inte på roten)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

repositoriesMode-lägen

dependencyResolutionManagement — ett block i settings.gradle som centraliserat hanterar repositories för alla moduler. Dök upp i Gradle 7.0 som ett alternativ till att deklarera repositories i varje build.gradle. Inuti blocket ställs repositoriesMode (läge: PREFER_PROJECT, PREFER_SETTINGS eller FAIL_ON_PROJECT_REPOS) och repositories (lista över repositories) in. Om repositoriesMode = PREFER_SETTINGS ignoreras modulens repositories — endast den centraliserade listan används.

repositoriesMode kan ha tre värden. PREFER_SETTINGS — repositories från build.gradle ignoreras, endast från settings.gradle används. PREFER_PROJECT — build.gradle-repositories har prioritet framför settings.gradle. FAIL_ON_PROJECT_REPOS — om en modul deklarerar egna repositories ger Gradle ett fel. För nya projekt rekommenderas PREFER_SETTINGS — detta garanterar att alla moduler använder samma repositories och eliminerar duplicering.

repositoriesMode = FAIL_ON_PROJECT_REPOS är särskilt användbart i team: om en utvecklare lägger till ett repository endast i en modul och de andra inte ser det uppstår situationen "works on my machine". FAIL_ON_PROJECT_REPOS tvingar fram att alla repositories deklareras centraliserat i settings.gradle, vilket förhindrar sådana situationer. Google rekommenderar FAIL_ON_PROJECT_REPOS för alla Android-projekt från och med AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — alla repositories endast här
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Privat 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") ?: ""
            }
        }
    }
}

// I modulens build.gradle behövs inte repositories längre!
// Alla repositories centraliserade i settings.gradle

Versionskataloger i settings.gradle

Versionskataloger är ett centraliserat sätt att hantera beroendeversioner via en TOML-fil. Från och med Gradle 7.4 är Versionskataloger den rekommenderade mekanismen för alla Android-projekt. Filen gradle/libs.versions.toml innehåller tre sektioner: [versions] (versioner), [libraries] (beroenden), [plugins] (plugins). I settings.gradle inkluderas Versionskatalogen via @Suppress("UnstableApiUsage") och enableFeaturePreview("VERSION_CATALOGS") (i äldre Gradle-versioner).

Efter att Versionskatalogen har inkluderats, i modulernas build.gradle specificeras beroenden via libs: implementation(libs.retrofit). IDE ger autokomplettering för libs. Katalogen genererar automatiskt type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles är grupper av beroenden som kan inkluderas med en rad. Versionskataloger stöder även arv — flera TOML-filer kan inkluderas.

Fördelar med Versionskataloger: en enda plats för versioner (behöver inte söka i alla build.gradle); type-safe åtkomst (fel i libs-namn upptäcks vid kompilering, inte vid körning); automatiska uppdateringar (Dependabot och Renovate stöder TOML); kompatibilitet med Convention Plugins. Google Firebase och AndroidX distribuerar egna TOML-kataloger. För migrering till Versionskataloger finns plugins som automatiskt flyttar versioner från build.gradle till 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" }

Avancerade inställningar: includeBuild och inkubationsfunktioner

includeBuild är ett direktiv för att skapa composite build: inkludera ett externt Gradle-projekt som en del av det aktuella bygget. Till skillnad från include (inkluderar en modul) inkluderar includeBuild ett helt projekt med egen settings.gradle, moduler och plugins. Composite builds används för: parallell utveckling av bibliotek (analys, nätverk) med applikationen; inkludering av Convention Plugins från ett separat repository; integration av build-logic-modulen.

Inkubationsfunktioner (Incubating Features) — experimentella Gradle-alternativ som aktiveras via enableFeaturePreview("FEATURE_NAME"). I AGP 8.7+ finns: TYPESAFE_PROJECT_ACCESSORS (type-safe åtkomst till projekt i ett multimodulprojekt: istället för project(":core:network") kan man skriva projects.core.network), STABLE_CONFIGURATION_CACHE (stabil konfigurationscache), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (artefakttransformering). Inkubationsfunktioner kan aktiveras i produktion, men API:n kan ändras i framtida versioner.

Gradle Enterprise och Build Scan konfigureras också via settings.gradle: plugins { id("com.gradle.enterprise") } med ett gradleEnterprise-block. Build Scan är en molntjänst som visar detaljerad information om varje bygge: exekveringstid för varje task, cachning, fel. Aktivering av Build Scan hjälper till att diagnostisera problem med bygghastighet. För opensource-projekt är Build Scan gratis.

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

// Användning av type-safe project accessors i build.gradle
// Istället för: implementation(project(":core:network"))
// Kan: implementation(projects.core.network)