settings.gradle: modulların əlavə edilməsi və pluginManagement

settings.gradle nədir?

settings.gradle (və ya Kotlin DSL üçün settings.gradle.kts) — Gradle-in Initialization mərhələsində icra etdiyi fayldır. O, layihənin iyerarxiyasını müəyyən edir, modulları əlavə edir, plaginlər və asılılıqlar üçün repozitoriyaları konfiqurasiya edir. settings.gradle olmadan Gradle hansı modulların yığılacağını və hansı plaginlərin mövcud olduğunu bilmir. Təkmodullu layihədə settings.gradle olmaya bilər — Gradle standart dəyərlərdən istifadə edir, lakin çoxmodullu layihələr üçün məcburidir.

settings.gradle faylı layihənin kök kataloqunda, əsas build.gradle ilə yanaşı yerləşir. Kök kataloqun tipik strukturu: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle build.gradle-dan əvvəl icra olunur — Initialization mərhələsində Gradle layihə ağacını qurur (Gradle API-də Project). Initialization bitdikdən sonra Configuration başlayır — hər bir modulun build.gradle faylının icrası.

Tarixən settings.gradle Gradle 0.7-də (2010) meydana çıxdı və əvvəlcə yalnız include direktivlərini ehtiva edirdi. Gradle-in inkişafı ilə settings.gradle-a pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) və versionCatalogs (Gradle 7.4) əlavə edildi. Müasir settings.gradle — bütün layihə üçün plaginləri, repozitoriyaları və versiyaları mərkəzləşdirən güclü konfiqurasiya faylıdır. Google bu imkanları AGP 8.0-dan başlayaraq Android Gradle Plugin-də təsbit edir.

settings.gradle vs build.gradle

settings.gradle layihənin strukturunu və qlobal parametrləri idarə edir (plaginlər, repozitoriyalar). build.gradle tikintini idarə edir (asılılıqlar, Android konfiqurasiyaları, tapşırıqlar). settings.gradle birinci icra olunur və Settings API-yə çıxışı var. build.gradle daha sonra icra olunur və Project API-yə çıxışı var. Heç bir modul konfiqurasiyası (android bloku, dependencies) settings.gradle-da ola bilməz — bu səhvdir.

include vasitəsilə modulların əlavə edilməsi

include direktivi settings.gradle-da əsas direktivdir. O, Gradle-ə hansı modulların tikintidə iştirak edəcəyini bildirir. include arqumenti modulun yoludur: include(":app") — kökdəki modulu əlavə edir, include(":core:network") — core/network/ alt kataloqundakı modulu əlavə edir. Əvvəldəki iki nöqtə yolun layihə kökünə nisbətən olduğunu göstərir. include-dan sonra Gradle avtomatik olaraq göstərilən kataloqda build.gradle-ı tapır və modulu layihə ağacına əlavə edir.

Hər include Gradle API-də include stringinə bərabər adla Project yaradır. Projektin adı digər modulların build.gradle-ında implementation(project(":module")) üçün istifadə olunur. Modul include vasitəsilə əlavə edilməyibsə, başqa moduldan ona istinad "Project not found" xətasına səbəb olur. Android Studio IDE də modulları Project panelində göstərmək üçün settings.gradle-dan istifadə edir — include olmayan modullar fayl ağacında görünmür.

include included builds və composite builds-i includeBuild("../library-project") vasitəsilə dəstəkləyir. Bu, bütün Gradle layihələrini xarici modullar kimi əlavə etməyə imkan verir. Included builds kitabxanaları tətbiq ilə paralel inkişaf etdirmək üçün faydalıdır: kitabxanadakı dəyişikliklər maven repozitoriyasına yayımlanmadan dərhal tətbiqdə görünür. İstehsalat tikintisində includeBuild adi maven asılılığı ilə əvəz olunur.

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

// Tətbiq modulları
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Xarici kitabxananın əlavə edilməsi (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Plugin Management Bloku

Resolution Strategy

pluginManagement — settings.gradle-da Gradle plaginlərinin haradan yüklənəcəyini müəyyən edən blokdur. Gradle 6.8-də plaginləri tətbiq etməzdən əvvəl mərkəzləşdirilmiş idarəetmə üçün meydana çıxdı. pluginManagement daxilində yerləşir: repositories (plaginləri axtarmaq üçün repozitoriyalar siyahısı), resolutionStrategy (versiyaların həlli qaydaları) və plugins (plagin versiyalarının açıq şəkildə göstərilməsi). Əgər pluginManagement qurulmayıbsa, Gradle build.gradle-dakı repozitoriyalardan istifadə edir — lakin plaginlər yalnız elan edildikdən sonra axtarılır, bu da plaqin tapılmadıqda xətalara səbəb olur.

Android layihəsində pluginManagement Versiya Kataloqlarının və ya Convention Plugins-in istifadə edildiyi hallarda məcburidir. pluginManagement olmadan Gradle build.gradle.kts-də tətbiq edərkən com.android.application plaginini tapa bilməyəcək. Tipik konfiqurasiya: repositories google() (Android plaginləri), mavenCentral() (üçüncü tərəf plaginləri) və gradlePluginPortal() (rəsmi Gradle plaginləri) ehtiva edir.

pluginManagement həmçinin plugins-i dəstəkləyir — versiyalarla plaginlərin elan edilməsi, daha sonra build.gradle-da versiya göstərilmədən tətbiq olunur. Bu, plagin versiyalarını mərkəzləşdirir: əgər 10 modul kotlin-android tətbiq edirsə, versiya pluginManagement-da bir dəfə göstərilir. Vacib: pluginManagement.plugins yalnız elan etməkdir. Plaqin özü build.gradle-da plugins { id("org.jetbrains.kotlin.android") } vasitəsilə tətbiq edilir.

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

    // Plagin versiyaları — mərkəzləşdirilmiş
    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 {
        // Bütün modullar üçün məcburi plagin versiyası
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Plaginlərin tətbiqi — apply false (kökə tətbiq edilməsin)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

repositoriesMode rejimləri

dependencyResolutionManagement — settings.gradle-da bütün modullar üçün repozitoriyaları mərkəzləşdirilmiş şəkildə idarə edən blokdur. Gradle 7.0-da hər build.gradle-da repositories elan etməyə alternativ olaraq meydana çıxdı. Blok daxilində repositoriesMode (rejim: PREFER_PROJECT, PREFER_SETTINGS və ya FAIL_ON_PROJECT_REPOS) və repositories (repozitoriyalar siyahısı) qurulur. Əgər repositoriesMode = PREFER_SETTINGS olarsa, modul repositories-ləri nəzərə alınmır — yalnız mərkəzləşdirilmiş siyahı istifadə olunur.

repositoriesMode üç qiymət ala bilər. PREFER_SETTINGS — build.gradle-dakı repozitoriyalar nəzərə alınmır, yalnız settings.gradle-dakılar istifadə olunur. PREFER_PROJECT — build.gradle repozitoriyaları settings.gradle üzərində prioritetə malikdir. FAIL_ON_PROJECT_REPOS — modul öz repozitoriyalarını elan edərsə, Gradle xəta verir. Yeni layihələr üçün PREFER_SETTINGS tövsiyə olunur — bu, bütün modulların eyni repozitoriyalardan istifadə etməsini təmin edir və təkrarlanmanı aradan qaldırır.

repositoriesMode = FAIL_ON_PROJECT_REPOS xüsusilə komandalarda faydalıdır: əgər proqramçı repozitoriyanı yalnız bir modula əlavə edərsə, digərləri onu görmür, "works on my machine" vəziyyəti yaranır. FAIL_ON_PROJECT_REPOS bütün repozitoriyaların settings.gradle-da mərkəzləşdirilmiş şəkildə elan edilməsini məcbur edir və belə halların qarşısını alır. Google AGP 8.0-dan başlayaraq bütün Android layihələri üçün FAIL_ON_PROJECT_REPOS tövsiyə edir.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — bütün repozitoriyalar yalnız burada
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Şəxsi maven repozitoriyası
        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") ?: ""
            }
        }
    }
}

// Modulun build.gradle-da repositories artıq lazım deyil!
// Bütün repozitoriyalar settings.gradle-da mərkəzləşdirilmişdir

settings.gradle-də Versiya Kataloqları

Versiya Kataloqları — TOML faylı vasitəsilə asılılıq versiyalarını idarə etməyin mərkəzləşdirilmiş üsuludur. Gradle 7.4-dən etibarən Versiya Kataloqları bütün Android layihələri üçün tövsiyə olunan mexanizmdir. gradle/libs.versions.toml faylı üç bölmədən ibarətdir: [versions] (versiyalar), [libraries] (asılılıqlar), [plugins] (plaginlər). settings.gradle-da Versiya Kataloqu @Suppress("UnstableApiUsage") və enableFeaturePreview("VERSION_CATALOGS") (köhnə Gradle versiyalarında) vasitəsilə əlavə edilir.

Versiya Kataloqu əlavə edildikdən sonra modulların build.gradle-ında asılılıqlar libs vasitəsilə göstərilir: implementation(libs.retrofit). IDE libs üçün avtomatik tamamlama təklif edir. Kataloq avtomatik olaraq type-safe accessors yaradır: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles — bir sətirlə əlavə edilə bilən asılılıq qruplarıdır. Versiya Kataloqları həmçinin vərəsəliyi dəstəkləyir — bir neçə TOML faylı əlavə edilə bilər.

Versiya Kataloqlarının üstünlükləri: versiyalar üçün vahid yer (bütün build.gradle fayllarında axtarmağa ehtiyac yoxdur); type-safe giriş (libs adında səhv kompilyasiya mərhələsində aşkarlanır, runtime-da deyil); avtomatik yeniləmələr (Dependabot və Renovate TOML-ı dəstəkləyir); Convention Plugins ilə uyğunluq. Google Firebase və AndroidX öz TOML kataloqlarını yayır. Versiya Kataloqlarına miqrasiya üçün versiyaları build.gradle-dan TOML-a avtomatik köçürən plaginlər mövcuddur.

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

Qabaqcıl parametrlər: includeBuild və inkubasiya xüsusiyyətləri

includeBuild — composite build yaratmaq üçün direktivdir: xarici Gradle layihəsini cari tikintinin bir hissəsi kimi əlavə etmək. include-dan (modulu əlavə edir) fərqli olaraq, includeBuild öz settings.gradle, modulları və plaginləri olan bütöv bir layihəni əlavə edir. Composite builds aşağıdakılar üçün istifadə olunur: kitabxanaların (analitika, şəbəkə) tətbiq ilə paralel inkişafı; ayrıca repozitoriyadan Convention Plugins-in əlavə edilməsi; build-logic modulunun inteqrasiyası.

İnkubasiya xüsusiyyətləri (Incubating Features) — enableFeaturePreview("FEATURE_NAME") vasitəsilə aktivləşdirilən eksperimental Gradle seçimləridir. AGP 8.7+-da mövcuddur: TYPESAFE_PROJECT_ACCESSORS (çoxmodullu layihədə layihələrə type-safe giriş: project(":core:network") əvəzinə projects.core.network yazmaq olar), STABLE_CONFIGURATION_CACHE (sabit konfiqurasiya keşi), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (artefaktların transformasiyası). İnkubasiya xüsusiyyətləri istehsalatda aktivləşdirilə bilər, lakin API gələcək versiyalarda dəyişə bilər.

Gradle Enterprise və Build Scan da settings.gradle vasitəsilə konfiqurasiya edilir: plugins { id("com.gradle.enterprise") } gradleEnterprise bloku ilə. Build Scan — hər bir tikinti haqqında ətraflı məlumat göstərən bulud xidmətidir: hər tapşırığın icra müddəti, keşləmə, xətalar. Build Scan-ı aktivləşdirmək tikinti sürəti ilə bağlı problemlərin diaqnostikasına kömək edir. Opensource layihələr üçün Build Scan pulsuzdur.

// İnkubasiya xüsusiyyətləri
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)
    }
}

// build.gradle-da type-safe project accessors istifadəsi
// Əvəzində: implementation(project(":core:network"))
// Olar: implementation(projects.core.network)