settings.gradle: vkládání modulů a pluginManagement

Co je settings.gradle?

settings.gradle (nebo settings.gradle.kts pro Kotlin DSL) je soubor, který Gradle spouští ve fázi Initialization. Definuje se v něm hierarchie projektu, přidávají se moduly, konfigurují úložiště pro pluginy a závislosti. Bez settings.gradle Gradle neví, které moduly sestavit a jaké pluginy jsou k dispozici. V jednomodulovém projektu může settings.gradle chybět — Gradle použije výchozí hodnoty, ale pro vícemodulové projekty je povinný.

Soubor settings.gradle se nachází v kořeni projektu, vedle kořenového build.gradle. Typická struktura kořene projektu: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle se spouští před build.gradle — ve fázi Initialization Gradle vytváří strom projektu (Project v Gradle API). Po dokončení Initialization začíná Configuration — spuštění build.gradle každého modulu.

Historicky se settings.gradle objevil v Gradle 0.7 (2010) a původně obsahoval pouze direktivy include. S vývojem Gradle byly do settings.gradle přidány pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) a versionCatalogs (Gradle 7.4). Moderní settings.gradle je výkonný konfigurační soubor, který centralizuje správu pluginů, úložišť a verzí pro celý projekt. Google tyto možnosti upevňuje v Android Gradle Plugin od AGP 8.0.

settings.gradle vs build.gradle

settings.gradle spravuje strukturu projektu a globální nastavení (pluginy, úložiště). build.gradle spravuje sestavení (závislosti, konfigurace Androidu, úkoly). settings.gradle se spouští jako první a má přístup k Settings API. build.gradle se spouští později a má přístup k Project API. Žádné konfigurace modulů (blok android, dependencies) nemohou být v settings.gradle — to je chyba.

Přidávání modulů pomocí include

Direktiva include je hlavní direktivou v settings.gradle. Sděluje Gradle, které moduly se mají účastnit sestavení. Argumentem include je cesta modulu: include(":app") — přidá modul v kořeni, include(":core:network") — modul v podadresáři core/network/. Dvojtečka na začátku označuje, že cesta je relativní ke kořeni projektu. Po include Gradle automaticky najde build.gradle v zadaném adresáři a přidá modul do stromu projektu.

Každé include vytváří Project v Gradle API s názvem rovným řetězci include. Název projektu se používá v implementation(project(":module")) v build.gradle jiných modulů. Pokud modul není zahrnut pomocí include, odkaz na něj z jiného modulu způsobí chybu "Project not found". Android Studio IDE také používá settings.gradle pro zobrazení modulů v panelu Project — moduly bez include nejsou viditelné ve stromu souborů.

include podporuje included builds a composite builds pomocí includeBuild("../library-project"). To umožňuje připojit celé Gradle projekty jako externí moduly. Included builds jsou užitečné pro paralelní vývoj knihoven s aplikací: změny v knihovně jsou okamžitě viditelné v aplikaci bez publikování do maven úložiště. V produkčním sestavení je includeBuild nahrazen běžnou maven závislostí.

// settings.gradle.kts — typická struktura
rootProject.name = "MyApp"

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

// Připojení externí knihovny (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Blok Plugin Management

Resolution Strategy

pluginManagement — blok v settings.gradle, který určuje, odkud se načítají Gradle pluginy. Objevil se v Gradle 6.8 pro centralizovanou správu pluginů před jejich aplikací. Uvnitř pluginManagement se nachází: repositories (seznam úložišť pro hledání pluginů), resolutionStrategy (pravidla pro řešení verzí) a plugins (explicitní určení verzí pluginů). Pokud pluginManagement není nastaven, Gradle použije úložiště z build.gradle — ale pluginy se hledají až po jejich deklarování, což vede k chybám, pokud plugin není nalezen.

V Android projektu je pluginManagement povinný, pokud se používají Katalogy verzí nebo Convention Plugins. Bez pluginManagement Gradle nenajde plugin com.android.application při aplikaci v build.gradle.kts. Typická konfigurace: repositories obsahuje google() (Android pluginy), mavenCentral() (pluginy třetích stran) a gradlePluginPortal() (oficiální Gradle pluginy).

pluginManagement také podporuje plugins — deklaraci pluginů s verzemi, které se pak aplikují v build.gradle bez uvádění verze. To centralizuje verze pluginů: pokud 10 modulů aplikuje kotlin-android, verze se uvádí jednou v pluginManagement. Důležité: pluginManagement.plugins je pouze deklarace. Samotný plugin se aplikuje v build.gradle pomocí plugins { id("org.jetbrains.kotlin.android") }.

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

    // Verze pluginů — centralizovaně
    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 {
        // Vynucená verze pluginu pro všechny moduly
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Aplikace pluginů — apply false (neaplikovat na kořen)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

Režimy repositoriesMode

dependencyResolutionManagement — blok v settings.gradle, který centralizovaně spravuje úložiště pro všechny moduly. Objevil se v Gradle 7.0 jako alternativa k deklarování repositories v každém build.gradle. Uvnitř bloku se nastavují repositoriesMode (režim: PREFER_PROJECT, PREFER_SETTINGS nebo FAIL_ON_PROJECT_REPOS) a repositories (seznam úložišť). Pokud repositoriesMode = PREFER_SETTINGS, modulová repositories jsou ignorována — používá se pouze centralizovaný seznam.

repositoriesMode může nabývat tří hodnot. PREFER_SETTINGS — úložiště z build.gradle jsou ignorována, používají se pouze z settings.gradle. PREFER_PROJECT — úložiště build.gradle mají prioritu před settings.gradle. FAIL_ON_PROJECT_REPOS — pokud modul deklaruje vlastní úložiště, Gradle vyvolá chybu. Pro nové projekty se doporučuje PREFER_SETTINGS — to zaručuje, že všechny moduly používají stejná úložiště, a eliminuje duplicitu.

repositoriesMode = FAIL_ON_PROJECT_REPOS je zvláště užitečný v týmech: pokud vývojář přidá úložiště pouze do jednoho modulu a ostatní ho nevidí, vzniká situace "works on my machine". FAIL_ON_PROJECT_REPOS vynucuje deklarování všech úložišť centralizovaně v settings.gradle, což takovým situacím předchází. Google doporučuje FAIL_ON_PROJECT_REPOS pro všechny Android projekty od AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — všechna úložiště jen zde
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Soukromé maven úložiště
        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") ?: ""
            }
        }
    }
}

// V build.gradle modulu už repositories nejsou potřeba!
// Všechna úložiště centralizována v settings.gradle

Katalogy verzí v settings.gradle

Katalogy verzí jsou centralizovaný způsob správy verzí závislostí pomocí TOML souboru. Od Gradle 7.4 jsou Katalogy verzí doporučeným mechanismem pro všechny Android projekty. Soubor gradle/libs.versions.toml obsahuje tři sekce: [versions] (verze), [libraries] (závislosti), [plugins] (pluginy). V settings.gradle se Katalog verzí připojuje pomocí @Suppress("UnstableApiUsage") a enableFeaturePreview("VERSION_CATALOGS") (ve starších verzích Gradle).

Po připojení Katalogu verzí se v build.gradle modulů závislosti uvádějí pomocí libs: implementation(libs.retrofit). IDE nabízí automatické dokončování pro libs. Katalog automaticky generuje type-safe accessory: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles jsou skupiny závislostí, které lze připojit jedním řádkem. Katalogy verzí také podporují dědičnost — lze připojit více TOML souborů.

Výhody Katalogů verzí: jedno místo pro verze (není třeba hledat ve všech build.gradle); type-safe přístup (chyba v názvu libs se odhalí ve fázi kompilace, ne za běhu); automatické aktualizace (Dependabot a Renovate podporují TOML); kompatibilita s Convention Plugins. Google Firebase a AndroidX distribuují vlastní TOML katalogy. Pro migraci na Katalogy verzí existují pluginy, které automaticky přenášejí verze z build.gradle do 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" }

Pokročilá nastavení: includeBuild a inkubační funkce

includeBuild je direktiva pro vytvoření composite build: připojení externího Gradle projektu jako součásti aktuálního sestavení. Na rozdíl od include (připojuje modul), includeBuild připojuje celý projekt s vlastním settings.gradle, moduly a pluginy. Composite builds se používají pro: paralelní vývoj knihoven (analytika, síť) s aplikací; připojení Convention Plugins z odděleného úložiště; integraci build-logic modulu.

Inkubační funkce (Incubating Features) — experimentální volby Gradle, které se zapínají pomocí enableFeaturePreview("FEATURE_NAME"). V AGP 8.7+ jsou k dispozici: TYPESAFE_PROJECT_ACCESSORS (type-safe přístup k projektům ve vícemodulovém projektu: místo project(":core:network") lze psát projects.core.network), STABLE_CONFIGURATION_CACHE (stabilní cache konfigurace), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformace artefaktů). Inkubační funkce lze zapnout v produkci, ale API se může v budoucích verzích změnit.

Gradle Enterprise a Build Scan se také konfigurují přes settings.gradle: plugins { id("com.gradle.enterprise") } s blokem gradleEnterprise. Build Scan je cloudová služba, která zobrazuje podrobné informace o každém sestavení: dobu provádění každého úkolu, cachování, chyby. Zapnutí Build Scan pomáhá diagnostikovat problémy s rychlostí sestavení. Pro opensource projekty je Build Scan zdarma.

// Inkubační funkce
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)
    }
}

// Použití type-safe project accessors v build.gradle
// Místo: implementation(project(":core:network"))
// Lze: implementation(projects.core.network)