settings.gradle: includerea modulelor și pluginManagement

Ce este settings.gradle?

settings.gradle (sau settings.gradle.kts pentru Kotlin DSL) este fișierul pe care Gradle îl execută în faza de Initialization. În el se definește ierarhia proiectului, se includ modulele, se configurează depozitele pentru pluginuri și dependențe. Fără settings.gradle, Gradle nu știe ce module să construiască și ce pluginuri sunt disponibile. Într-un proiect cu un singur modul, settings.gradle poate lipsi — Gradle folosește valorile implicite, dar pentru proiecte multi-modul este obligatoriu.

Fișierul settings.gradle se află în rădăcina proiectului, lângă build.gradle rădăcină. Structura tipică a rădăcinii proiectului: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle se execută înainte de build.gradle — în faza de Initialization, Gradle construiește arborele proiectului (Project în API-ul Gradle). După finalizarea Initialization, începe Configuration — executarea build.gradle pentru fiecare modul.

Istoric, settings.gradle a apărut în Gradle 0.7 (2010) și inițial conținea doar directive include. Odată cu dezvoltarea Gradle, la settings.gradle s-au adăugat pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) și versionCatalogs (Gradle 7.4). settings.gradle modern este un fișier de configurare puternic care centralizează gestionarea pluginurilor, depozitelor și versiunilor pentru întregul proiect. Google consolidează aceste capacități în Android Gradle Plugin începând cu AGP 8.0.

settings.gradle vs build.gradle

settings.gradle gestionează structura proiectului și setările globale (pluginuri, depozite). build.gradle gestionează build-ul (dependențe, configurații Android, taskuri). settings.gradle se execută primul și are acces la Settings API. build.gradle se execută ulterior și are acces la Project API. Nicio configurație de modul (blocul android, dependencies) nu poate fi în settings.gradle — aceasta este o eroare.

Includerea modulelor prin include

Directiva include este directiva principală în settings.gradle. Ea informează Gradle ce module trebuie să participe la build. Argumentul include este o cale către modul: include(":app") — include modulul din rădăcină, include(":core:network") — modulul din subdirectorul core/network/. Două puncte la început indică faptul că calea este relativă la rădăcina proiectului. După include, Gradle găsește automat build.gradle în directorul specificat și adaugă modulul în arborele proiectului.

Fiecare include creează un Project în API-ul Gradle cu numele egal cu șirul include. Numele proiectului este utilizat în implementation(project(":module")) în build.gradle ale altor module. Dacă modulul nu este inclus prin include, referința la el dintr-un alt modul va genera eroarea "Project not found". Android Studio IDE utilizează, de asemenea, settings.gradle pentru afișarea modulelor în panoul Project — modulele fără include nu sunt vizibile în arborele de fișiere.

include suportă included builds și composite builds prin includeBuild("../library-project"). Acest lucru permite includerea unor proiecte Gradle întregi ca module externe. Included builds sunt utile pentru dezvoltarea bibliotecilor în paralel cu aplicația: modificările din bibliotecă sunt imediat vizibile în aplicație fără publicare în depozitul maven. În build-ul de producție, includeBuild este înlocuit cu o dependență maven obișnuită.

// settings.gradle.kts — structură tipică
rootProject.name = "MyApp"

// Modulele aplicației
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Includerea unei biblioteci externe (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Blocul Plugin Management

Resolution Strategy

pluginManagement — un bloc în settings.gradle care stabilește de unde se încarcă pluginurile Gradle. A apărut în Gradle 6.8 pentru gestionarea centralizată a pluginurilor înainte de aplicarea lor. În interiorul pluginManagement se află: repositories (lista depozitelor pentru căutarea pluginurilor), resolutionStrategy (reguli de rezolvare a versiunilor) și plugins (specificarea explicită a versiunilor pluginurilor). Dacă pluginManagement nu este configurat, Gradle folosește depozitele din build.gradle — dar pluginurile sunt căutate doar după ce sunt declarate, ceea ce duce la erori dacă pluginul nu este găsit.

În proiectul Android, pluginManagement este obligatoriu dacă se folosesc Cataloagele de versiuni sau Convention Plugins. Fără pluginManagement, Gradle nu va putea găsi pluginul com.android.application la aplicarea în build.gradle.kts. Configurația tipică: repositories conține google() (pluginuri Android), mavenCentral() (pluginuri terțe) și gradlePluginPortal() (pluginuri oficiale Gradle).

pluginManagement suportă, de asemenea, plugins — declararea pluginurilor cu versiuni care sunt apoi aplicate în build.gradle fără specificarea versiunii. Aceasta centralizează versiunile pluginurilor: dacă 10 module aplică kotlin-android, versiunea este specificată o dată în pluginManagement. Important: pluginManagement.plugins este doar o declarație. Pluginul în sine se aplică în build.gradle prin plugins { id("org.jetbrains.kotlin.android") }.

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

    // Versiuni de pluginuri — centralizat
    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 {
        // Versiune forțată a pluginului pentru toate modulele
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Aplicarea pluginurilor — apply false (nu se aplică la rădăcină)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

Modurile repositoriesMode

dependencyResolutionManagement — un bloc în settings.gradle care gestionează centralizat depozitele pentru toate modulele. A apărut în Gradle 7.0 ca alternativă la declararea repositories în fiecare build.gradle. În interiorul blocului se setează repositoriesMode (modul: PREFER_PROJECT, PREFER_SETTINGS sau FAIL_ON_PROJECT_REPOS) și repositories (lista depozitelor). Dacă repositoriesMode = PREFER_SETTINGS, repositories-urile modulelor sunt ignorate — se folosește doar lista centralizată.

repositoriesMode poate lua trei valori. PREFER_SETTINGS — depozitele din build.gradle sunt ignorate, se folosesc doar cele din settings.gradle. PREFER_PROJECT — depozitele build.gradle au prioritate față de settings.gradle. FAIL_ON_PROJECT_REPOS — dacă modulul declară propriile depozite, Gradle generează o eroare. Pentru proiecte noi, se recomandă PREFER_SETTINGS — garantează că toate modulele folosesc aceleași depozite și elimină duplicarea.

repositoriesMode = FAIL_ON_PROJECT_REPOS este deosebit de util în echipe: dacă un dezvoltator adaugă un depozit doar într-un modul, iar celelalte nu îl văd, apare situația "works on my machine". FAIL_ON_PROJECT_REPOS forțează declararea tuturor depozitelor centralizat în settings.gradle, prevenind astfel astfel de situații. Google recomandă FAIL_ON_PROJECT_REPOS pentru toate proiectele Android începând cu AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — toate depozitele doar aici
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

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

// În build.gradle al modulului, repositories nu mai sunt necesare!
// Toate depozitele centralizate în settings.gradle

Cataloagele de versiuni în settings.gradle

Cataloagele de versiuni reprezintă o modalitate centralizată de gestionare a versiunilor dependențelor prin fișierul TOML. Începând cu Gradle 7.4, Cataloagele de versiuni sunt mecanismul recomandat pentru toate proiectele Android. Fișierul gradle/libs.versions.toml conține trei secțiuni: [versions] (versiuni), [libraries] (dependențe), [plugins] (pluginuri). În settings.gradle, Catalogul de versiuni se include prin @Suppress("UnstableApiUsage") și enableFeaturePreview("VERSION_CATALOGS") (în versiunile vechi de Gradle).

După includerea Catalogului de versiuni, în build.gradle ale modulelor dependențele sunt specificate prin libs: implementation(libs.retrofit). IDE oferă autocompletare pentru libs. Catalogul generează automat type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles sunt grupuri de dependențe care pot fi incluse cu o singură linie. Cataloagele de versiuni suportă și moștenirea — se pot include mai multe fișiere TOML.

Avantajele Cataloagelor de versiuni: un singur loc pentru versiuni (nu mai trebuie căutat în toate build.gradle); acces type-safe (eroarea în numele libs este detectată în faza de compilare, nu la runtime); actualizări automate (Dependabot și Renovate suportă TOML); compatibilitate cu Convention Plugins. Google Firebase și AndroidX distribuie propriile cataloage TOML. Pentru migrarea la Cataloagele de versiuni există pluginuri care transferă automat versiunile din build.gradle în 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" }

Setări avansate: includeBuild și funcții experimentale

includeBuild este o directivă pentru crearea unui composite build: includerea unui proiect Gradle extern ca parte a build-ului curent. Spre deosebire de include (include un modul), includeBuild include un întreg proiect cu propriul settings.gradle, module și pluginuri. Composite builds sunt utilizate pentru: dezvoltarea paralelă a bibliotecilor (analitică, rețea) cu aplicația; includerea Convention Plugins dintr-un depozit separat; integrarea modulului build-logic.

Funcțiile experimentale (Incubating Features) — opțiuni experimentale Gradle care se activează prin enableFeaturePreview("FEATURE_NAME"). În AGP 8.7+ sunt disponibile: TYPESAFE_PROJECT_ACCESSORS (acces type-safe la proiecte într-un proiect multi-modul: în loc de project(":core:network") se poate scrie projects.core.network), STABLE_CONFIGURATION_CACHE (cache stabil al configurației), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformarea artifactelor). Funcțiile experimentale pot fi activate în producție, dar API-ul se poate schimba în versiunile viitoare.

Gradle Enterprise și Build Scan se configurează, de asemenea, prin settings.gradle: plugins { id("com.gradle.enterprise") } cu blocul gradleEnterprise. Build Scan este un serviciu cloud care afișează informații detaliate despre fiecare build: timpul de execuție al fiecărui task, cache, erori. Activarea Build Scan ajută la diagnosticarea problemelor de viteză a build-ului. Pentru proiectele opensource, Build Scan este gratuit.

// Funcții experimentale
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)
    }
}

// Utilizarea type-safe project accessors în build.gradle
// În loc de: implementation(project(":core:network"))
// Se poate: implementation(projects.core.network)