settings.gradle: modulok hozzáadása és pluginManagement

Mi az a settings.gradle?

settings.gradle (vagy Kotlin DSL esetén settings.gradle.kts) az a fájl, amelyet a Gradle az Initialization fázisban hajt végre. Ebben határozzák meg a projekt hierarchiáját, csatolják a modulokat, konfigurálják a plugintárolókat és függőségeket. settings.gradle nélkül a Gradle nem tudja, mely modulokat kell felépíteni és mely pluginok érhetők el. Egymodulos projektben a settings.gradle hiányozhat — a Gradle alapértelmezett értékeket használ, de többmodulos projekteknél kötelező.

A settings.gradle fájl a projekt gyökerében található, a gyökér build.gradle mellett. A projekt gyökerének tipikus felépítése: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. A settings.gradle a build.gradle előtt fut le — az Initialization fázisban a Gradle felépíti a projektfát (Project a Gradle API-ban). Az Initialization befejezése után kezdődik a Configuration — az egyes modulok build.gradle fájljainak végrehajtása.

Történelmileg a settings.gradle a Gradle 0.7-ben (2010) jelent meg, és kezdetben csak include utasításokat tartalmazott. A Gradle fejlődésével a settings.gradle-hez hozzáadták a pluginManagement-et (Gradle 6.8), a dependencyResolutionManagement-et (Gradle 7.0) és a versionCatalogs-ot (Gradle 7.4). A modern settings.gradle egy erőteljes konfigurációs fájl, amely központosítja a pluginok, tárolók és verziók kezelését a teljes projektre vonatkozóan. A Google ezeket a képességeket az AGP 8.0-tól kezdve rögzíti az Android Gradle Plugin-ben.

settings.gradle vs build.gradle

settings.gradle a projekt szerkezetét és a globális beállításokat kezeli (pluginok, tárolók). build.gradle a buildet kezeli (függőségek, Android-konfigurációk, feladatok). A settings.gradle fut le először, és hozzáfér a Settings API-hoz. A build.gradle később fut le, és hozzáfér a Project API-hoz. Semmilyen modulkonfiguráció (android blokk, dependencies) nem lehet a settings.gradle-ben — ez hiba.

Modulok hozzáadása include segítségével

Az include utasítás a settings.gradle elsődleges utasítása. Közli a Gradle-lel, hogy mely modulok vegyenek részt a buildben. Az include argumentuma a modul elérési útja: include(":app") — a gyökérben lévő modult adja hozzá, include(":core:network") — a core/network/ alkönyvtárban lévő modult adja hozzá. A kettőspont az elején azt jelzi, hogy az elérési út a projekt gyökeréhez viszonyított. Az include után a Gradle automatikusan megtalálja a build.gradle-t a megadott könyvtárban, és hozzáadja a modult a projektfához.

Minden include létrehoz egy Project objektumot a Gradle API-ban, amelynek neve megegyezik az include sztringgel. A projektnevet a implementation(project(":module")) használja más modulok build.gradle fájljaiban. Ha egy modul nem került beillesztésre include segítségével, akkor egy másik modulból való hivatkozás "Project not found" hibát eredményez. Az Android Studio IDE is a settings.gradle-t használja a modulok Project panelen való megjelenítéséhez — a include nélküli modulok nem láthatók a fállistában.

Az include támogatja az included builds és composite builds funkciókat a includeBuild("../library-project") segítségével. Ez lehetővé teszi teljes Gradle-projektek külső modulként való csatolását. Az included builds hasznos a könyvtárak párhuzamos fejlesztéséhez az alkalmazással: a könyvtárban végzett változtatások azonnal láthatók az alkalmazásban anélkül, hogy közzé kellene tenni azokat egy maven-tárhelyen. Éles buildben az includeBuild helyett szokásos maven-függőséget használnak.

// settings.gradle.kts — tipikus felépítés
rootProject.name = "MyApp"

// Alkalmazásmodulok
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Külső könyvtár csatolása (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Plugin Management blokk

Resolution Strategy

pluginManagement — egy blokk a settings.gradle-ben, amely meghatározza, honnan töltődnek be a Gradle-pluginok. A Gradle 6.8-ban jelent meg a pluginok központosított kezelésére, még azok alkalmazása előtt. A pluginManagement-en belül található: repositories (a pluginok keresésére szolgáló tárolók listája), resolutionStrategy (verziófeloldási szabályok) és plugins (a pluginverziók explicit megadása). Ha a pluginManagement nincs beállítva, a Gradle a build.gradle-ből származó tárolókat használja — de a pluginok csak a deklarálásuk után kerülnek keresésre, ami hibákhoz vezet, ha a plugin nem található.

Android-projektben a pluginManagement kötelező, ha Verziókatalógusokat vagy Convention Plugins-t használnak. pluginManagement nélkül a Gradle nem találja a com.android.application plugint a build.gradle.kts-ben történő alkalmazáskor. Tipikus konfiguráció: a repositories tartalmazza a google()-t (Android-pluginok), a mavenCentral()-t (harmadik féltől származó pluginok) és a gradlePluginPortal()-t (hivatalos Gradle-pluginok).

A pluginManagement támogatja a plugins blokkot is — a pluginok verziókkal együtt történő deklarálását, amelyek azután a build.gradle-ben verzió megadása nélkül alkalmazhatók. Ez központosítja a pluginverziókat: ha 10 modul alkalmazza a kotlin-android plugint, a verziót egyszer kell megadni a pluginManagement-ben. Fontos: a pluginManagement.plugins csak deklaráció. Magát a plugint a build.gradle-ben kell alkalmazni a plugins { id("org.jetbrains.kotlin.android") } segítségével.

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

    // Pluginverziók — központosítottan
    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 {
        // Kényszerített pluginverzió minden modulhoz
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Pluginok alkalmazása — apply false (ne alkalmazza a gyökérre)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

repositoriesMode módok

dependencyResolutionManagement — egy blokk a settings.gradle-ben, amely központosítottan kezeli a tárolókat az összes modul számára. A Gradle 7.0-ban jelent meg alternatívaként a repositories deklarálására minden egyes build.gradle-ben. A blokkon belül állítható be a repositoriesMode (mód: PREFER_PROJECT, PREFER_SETTINGS vagy FAIL_ON_PROJECT_REPOS) és a repositories (tárolók listája). Ha a repositoriesMode = PREFER_SETTINGS, a modul szintű repositories figyelmen kívül marad — csak a központosított lista használatos.

A repositoriesMode három értéket vehet fel. PREFER_SETTINGS — a build.gradle-ből származó tárolók figyelmen kívül maradnak, csak a settings.gradle-ből származók használatosak. PREFER_PROJECT — a build.gradle tárolói elsőbbséget élveznek a settings.gradle-lel szemben. FAIL_ON_PROJECT_REPOS — ha egy modul saját tárolókat deklarál, a Gradle hibát dob. Új projektekhez a PREFER_SETTINGS ajánlott — ez garantálja, hogy minden modul ugyanazokat a tárolókat használja, és megszünteti a duplikációt.

A repositoriesMode = FAIL_ON_PROJECT_REPOS különösen hasznos csapatokban: ha egy fejlesztő csak egy modulhoz ad hozzá tárolót, a többiek pedig nem látják, "works on my machine" helyzet alakul ki. A FAIL_ON_PROJECT_REPOS kikényszeríti, hogy minden tárolót központosítottan, a settings.gradle-ben deklaráljanak, ami megelőzi az ilyen helyzeteket. A Google a FAIL_ON_PROJECT_REPOS-t ajánlja minden Android-projekthez az AGP 8.0-tól kezdve.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — minden tároló csak itt
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Privát maven-tároló
        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") ?: ""
            }
        }
    }
}

// A modul build.gradle-jében a repositories már nem szükséges!
// Minden tároló központosítva a settings.gradle-ben

Verziókatalógusok a settings.gradle-ben

Verziókatalógusok — a függőségi verziók központosított kezelésének módja TOML-fájlon keresztül. A Gradle 7.4-től kezdve a Verziókatalógusok az ajánlott mechanizmus minden Android-projekthez. A gradle/libs.versions.toml fájl három szekciót tartalmaz: [versions] (verziók), [libraries] (függőségek), [plugins] (pluginok). A settings.gradle-ben a Verziókatalógus a @Suppress("UnstableApiUsage") és enableFeaturePreview("VERSION_CATALOGS") segítségével csatlakozik (régebbi Gradle-verziókban).

A Verziókatalógus csatlakoztatása után a modulok build.gradle fájljaiban a függőségek a libs segítségével adhatók meg: implementation(libs.retrofit). Az IDE automatikus kiegészítést biztosít a libs-hez. A katalógus automatikusan type-safe accessorokat generál: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. A Bundles olyan függőségi csoportok, amelyek egy sorral hozzáadhatók. A Verziókatalógusok az öröklődést is támogatják — több TOML-fájl is csatlakoztatható.

A Verziókatalógusok előnyei: egyetlen hely a verziók számára (nem kell keresgélni az összes build.gradle-ben); type-safe hozzáférés (a libs név hibája fordítási időben kiderül, nem futásidőben); automatikus frissítések (a Dependabot és a Renovate támogatja a TOML-t); kompatibilitás a Convention Plugins-szel. A Google Firebase és az AndroidX saját TOML-katalógusokat terjeszt. A Verziókatalógusokra való migráláshoz léteznek pluginok, amelyek automatikusan áthelyezik a verziókat a build.gradle-ből a TOML-ba.

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

Haladó beállítások: includeBuild és inkubációs funkciók

includeBuild — utasítás composite build létrehozásához: külső Gradle-projekt csatolása a jelenlegi build részeként. Ellentétben az include-dal (modult csatol), az includeBuild egy teljes projektet csatol saját settings.gradle-lel, modulokkal és pluginokkal. A composite builds a következőkre használható: könyvtárak (analitika, hálózat) párhuzamos fejlesztése az alkalmazással; Convention Plugins csatolása külön tárolóból; a build-logic modul integrálása.

Inkubációs funkciók (Incubating Features) — kísérleti Gradle-opciók, amelyek az enableFeaturePreview("FEATURE_NAME") segítségével kapcsolhatók be. Az AGP 8.7+-ben elérhetők: TYPESAFE_PROJECT_ACCESSORS (type-safe hozzáférés a projektekhez többmodulos projektben: a project(":core:network") helyett projects.core.network írható), STABLE_CONFIGURATION_CACHE (stabil konfigurációs gyorsítótár), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (artefaktumok transzformációja). Az inkubációs funkciók éles környezetben is bekapcsolhatók, de az API a jövőbeli verziókban változhat.

Gradle Enterprise és Build Scan szintén a settings.gradle-ben konfigurálhatók: plugins { id("com.gradle.enterprise") } a gradleEnterprise blokkal. A Build Scan egy felhőszolgáltatás, amely részletes információkat jelenít meg minden buildről: az egyes feladatok végrehajtási ideje, gyorsítótárazás, hibák. A Build Scan bekapcsolása segít diagnosztizálni a build sebességével kapcsolatos problémákat. Nyílt forráskódú projektek számára a Build Scan ingyenes.

// Inkubációs funkciók
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)
    }
}

// Type-safe project accessors használata a build.gradle-ben
// Helyette: implementation(project(":core:network"))
// Lehet: implementation(projects.core.network)