settings.gradle: dołączanie modułów i pluginManagement

Co to jest settings.gradle?

settings.gradle (lub settings.gradle.kts dla Kotlin DSL) to plik, który Gradle wykonuje na etapie Initialization. Określa on hierarchię projektu, dołącza moduły, konfiguruje repozytoria dla wtyczek i zależności. Bez settings.gradle Gradle nie wie, które moduły kompilować i jakie wtyczki są dostępne. W projekcie jednomodułowym settings.gradle może nie być obecny — Gradle używa wartości domyślnych, ale dla projektów wielomodułowych jest wymagany.

Plik settings.gradle znajduje się w katalogu głównym projektu, obok głównego build.gradle. Typowa struktura katalogu głównego projektu: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle jest wykonywany przed build.gradle — na etapie Initialization Gradle buduje drzewo projektu (Project w API Gradle). Po zakończeniu Initialization rozpoczyna się Configuration — wykonanie build.gradle każdego modułu.

Historycznie settings.gradle pojawił się w Gradle 0.7 (2010) i początkowo zawierał tylko dyrektywy include. Wraz z rozwojem Gradle do settings.gradle dodano pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) i versionCatalogs (Gradle 7.4). Współczesny settings.gradle to potężny plik konfiguracyjny, który centralizuje zarządzanie wtyczkami, repozytoriami i wersjami dla całego projektu. Google utrwala te możliwości w Android Gradle Plugin od AGP 8.0.

settings.gradle vs build.gradle

settings.gradle zarządza strukturą projektu i ustawieniami globalnymi (wtyczki, repozytoria). build.gradle zarządza kompilacją (zależności, konfiguracje Android, zadania). settings.gradle jest wykonywany jako pierwszy i ma dostęp do Settings API. build.gradle jest wykonywany później i ma dostęp do Project API. Żadne konfiguracje modułów (blok android, dependencies) nie mogą znajdować się w settings.gradle — to błąd.

Dołączanie modułów przez include

Dyrektywa include jest podstawową w settings.gradle. Informuje Gradle, które moduły mają uczestniczyć w kompilacji. Argument include to ścieżka modułu: include(":app") — dołącza moduł w katalogu głównym, include(":core:network") — moduł w podkatalogu core/network/. Dwukropek na początku wskazuje, że ścieżka jest względna względem katalogu głównego projektu. Po include Gradle automatycznie znajduje build.gradle we wskazanym katalogu i dodaje moduł do drzewa projektu.

Każde include tworzy Project w API Gradle z nazwą równą stringowi include. Nazwa projektu jest używana w implementation(project(":module")) w build.gradle innych modułów. Jeśli moduł nie został dołączony przez include, odwołanie do niego z innego modułu spowoduje błąd "Project not found". Android Studio IDE również używa settings.gradle do wyświetlania modułów w panelu Project — moduły bez include nie są widoczne w drzewie plików.

include obsługuje included builds i composite builds przez includeBuild("../library-project"). Pozwala to dołączać całe projekty Gradle jako moduły zewnętrzne. Included builds są przydatne do równoległego rozwijania bibliotek z aplikacją: zmiany w bibliotece są natychmiast widoczne w aplikacji bez publikowania w repozytorium maven. W kompilacji produkcyjnej includeBuild jest zastępowany zwykłą zależnością maven.

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

// Moduły aplikacji
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Dołączanie zewnętrznej biblioteki (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Blok Plugin Management

Resolution Strategy

pluginManagement — blok w settings.gradle, który określa, skąd ładować wtyczki Gradle. Pojawił się w Gradle 6.8 do scentralizowanego zarządzania wtyczkami przed ich zastosowaniem. Wewnątrz pluginManagement znajdują się: repositories (lista repozytoriów do wyszukiwania wtyczek), resolutionStrategy (reguły rozwiązywania wersji) i plugins (jawne określenie wersji wtyczek). Jeśli pluginManagement nie jest ustawiony, Gradle używa repozytoriów z build.gradle — ale wtyczki są wyszukiwane dopiero po ich zadeklarowaniu, co prowadzi do błędów, jeśli wtyczka nie zostanie znaleziona.

W projekcie Android pluginManagement jest wymagany, jeśli używane są Katalogi wersji lub Convention Plugins. Bez pluginManagement Gradle nie będzie mógł znaleźć wtyczki com.android.application przy zastosowaniu w build.gradle.kts. Typowa konfiguracja: repositories zawiera google() (wtyczki Android), mavenCentral() (wtyczki zewnętrzne) i gradlePluginPortal() (oficjalne wtyczki Gradle).

pluginManagement obsługuje również plugins — deklarowanie wtyczek z wersjami, które następnie są stosowane w build.gradle bez podawania wersji. To centralizuje wersje wtyczek: jeśli 10 modułów stosuje kotlin-android, wersja jest określana raz w pluginManagement. Ważne: pluginManagement.plugins to tylko deklaracja. Sama wtyczka jest stosowana w build.gradle przez plugins { id("org.jetbrains.kotlin.android") }.

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

    // Wersje wtyczek — centralnie
    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 {
        // Wymuszona wersja wtyczki dla wszystkich modułów
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Stosowanie wtyczek — apply false (nie stosować do katalogu głównego)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

Tryby repositoriesMode

dependencyResolutionManagement — blok w settings.gradle, scentralizowanie zarządzający repozytoriami dla wszystkich modułów. Pojawił się w Gradle 7.0 jako alternatywa dla deklarowania repositories w każdym build.gradle. Wewnątrz bloku ustawiane są repositoriesMode (tryb: PREFER_PROJECT, PREFER_SETTINGS lub FAIL_ON_PROJECT_REPOS) i repositories (lista repozytoriów). Jeśli repositoriesMode = PREFER_SETTINGS, modułowe repositories są ignorowane — używana jest tylko scentralizowana lista.

repositoriesMode może przyjmować trzy wartości. PREFER_SETTINGS — repozytoria z build.gradle są ignorowane, używane są tylko z settings.gradle. PREFER_PROJECT — repozytoria build.gradle mają priorytet nad settings.gradle. FAIL_ON_PROJECT_REPOS — jeśli moduł deklaruje własne repozytoria, Gradle zgłasza błąd. Dla nowych projektów zalecany jest PREFER_SETTINGS — gwarantuje to, że wszystkie moduły korzystają z tych samych repozytoriów i eliminuje powielanie.

repositoriesMode = FAIL_ON_PROJECT_REPOS jest szczególnie przydatny w zespołach: jeśli programista doda repozytorium tylko w jednym module, a pozostałe go nie widzą, powstaje sytuacja "works on my machine". FAIL_ON_PROJECT_REPOS wymusza deklarowanie wszystkich repozytoriów centralnie w settings.gradle, co zapobiega takim sytuacjom. Google zaleca FAIL_ON_PROJECT_REPOS dla wszystkich projektów Android od AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — wszystkie repozytoria tylko tutaj
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Prywatne repozytorium maven
        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") ?: ""
            }
        }
    }
}

// W build.gradle modułu repositories nie są już potrzebne!
// Wszystkie repozytoria scentralizowane w settings.gradle

Katalogi wersji w settings.gradle

Katalogi wersji to scentralizowany sposób zarządzania wersjami zależności przez plik TOML. Od Gradle 7.4 Katalogi wersji są zalecanym mechanizmem dla wszystkich projektów Android. Plik gradle/libs.versions.toml zawiera trzy sekcje: [versions] (wersje), [libraries] (zależności), [plugins] (wtyczki). W settings.gradle Katalog wersji jest dołączany przez @Suppress("UnstableApiUsage") i enableFeaturePreview("VERSION_CATALOGS") (w starszych wersjach Gradle).

Po podłączeniu Katalogu wersji, w build.gradle modułów zależności są określane przez libs: implementation(libs.retrofit). IDE oferuje autouzupełnianie dla libs. Katalog automatycznie generuje type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles to grupy zależności, które można dołączyć jedną linią. Katalogi wersji obsługują również dziedziczenie — można dołączać wiele plików TOML.

Zalety Katalogów wersji: jedno miejsce dla wersji (nie trzeba szukać po wszystkich build.gradle); type-safe dostęp (błąd w nazwie libs zostanie wykryty na etapie kompilacji, a nie w runtime); automatyczne aktualizacje (Dependabot i Renovate obsługują TOML); kompatybilność z Convention Plugins. Google Firebase i AndroidX dystrybuują własne katalogi TOML. Do migracji na Katalogi wersji istnieją wtyczki, które automatycznie przenoszą wersje 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" }

Zaawansowane ustawienia: includeBuild i funkcje eksperymentalne

includeBuild to dyrektywa do tworzenia composite build: dołączania zewnętrznego projektu Gradle jako części bieżącej kompilacji. W przeciwieństwie do include (dołącza moduł), includeBuild dołącza cały projekt z własnym settings.gradle, modułami i wtyczkami. Composite builds są używane do: równoległego rozwijania bibliotek (analityka, sieć) z aplikacją; dołączania Convention Plugins z osobnego repozytorium; integracji modułu build-logic.

Funkcje eksperymentalne (Incubating Features) — opcje eksperymentalne Gradle, które są włączane przez enableFeaturePreview("FEATURE_NAME"). W AGP 8.7+ dostępne są: TYPESAFE_PROJECT_ACCESSORS (type-safe dostęp do projektów w projekcie wielomodułowym: zamiast project(":core:network") można pisać projects.core.network), STABLE_CONFIGURATION_CACHE (stabilne buforowanie konfiguracji), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformacja artefaktów). Funkcje eksperymentalne można włączać w produkcji, ale API może się zmienić w przyszłych wersjach.

Gradle Enterprise i Build Scan również są konfigurowane przez settings.gradle: plugins { id("com.gradle.enterprise") } z blokiem gradleEnterprise. Build Scan to usługa chmurowa, która pokazuje szczegółowe informacje o każdej kompilacji: czas wykonania każdego zadania, buforowanie, błędy. Włączenie Build Scan pomaga diagnozować problemy z szybkością kompilacji. Dla projektów opensource Build Scan jest bezpłatny.

// Funkcje eksperymentalne
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)
    }
}

// Używanie type-safe project accessors w build.gradle
// Zamiast: implementation(project(":core:network"))
// Można: implementation(projects.core.network)