build.gradle: bu nədir, sintaksisi və Android-də konfiqurasiyası

build.gradle nədir?

build.gradle — Android tətbiqinin tərtibinin bütün aspektlərini idarə edən Groovy (.gradle uzantısı) və ya Kotlin (.gradle.kts) dilində quruluş skriptidir. Gradle — 2013-cü ildə Google tərəfindən Android üçün standart olaraq qəbul edilmiş avtomatik quruluş sistemidir. build.gradle aşağıdakıları təsvir edir: hansı plaginlərin tətbiq edildiyi (Android, Kotlin, kitabxanalar), hansı asılılıqların qoşulduğu, hansı SDK versiyalarının istifadə edildiyi, tətbiqin necə imzalanacağı və harada dərc ediləcəyi.

Quruluş prosesi üç mərhələni əhatə edir: Initialization (modulların müəyyən edilməsi), Configuration (build.gradle skriptlərinin icrası), Execution (tapşırıqların icrası). build.gradle Konfiqurasiya mərhələsində icra olunur, bu zaman Gradle tapşırıq qrafını yaradır. Bu məqamda Build Variant-lar müəyyən edilir, asılılıqlar hesablanır və tapşırıqlar konfiqurasiya edilir. Vacib: build.gradle sadəcə konfiqurasiya deyil, koddur. Burada şərtlər, dövrlər, metod çağırışları və xarici skriptlərdən istifadə etmək olar.

Gradle faylları modulun kökündə (app/build.gradle) və layihənin kökündə (build.gradle) saxlanılır. Bundan əlavə, Gradle apply from — xarici Gradle skriptlərinin qoşulmasını dəstəkləyir. Bu, təkrarlanan məntiqi ümumi parametrləri olan fayllara çıxarmağa imkan verir. Convention Plugins (AGP 7+) ilə apply from köhnəlmiş sayılır — Convention Plugins modullar arasında konfiqurasiyanın təkrar istifadəsi üçün type-safe və kompozit üsul təmin edir.

build.gradle-in təkamülü

2013-cü ildən build.gradle sintaksisi əhəmiyyətli dəyişikliklərə məruz qalmışdır: dinamik konfiqurasiyalı Groovy-dən compile-time yoxlamalı Kotlin DSL-ə qədər. AGP 1.0 versiyasından 8.7 (2025)-ə qədər təkamül etmişdir. Əsas mərhələlər: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (standart olaraq Kotlin DSL, Java 11 min), AGP 8.0 (non-transitive R classes, Kotlin-də quruluş konfiqurasiyası), AGP 8.7 (kapt əvəzinə KSP, sürətli konfiqurasiya).

Project-level və Module-level build.gradle

Project-level build.gradle (kök) bütün modullar üçün ümumi olan plaginləri, depozitoriyaları və konfiqurasiyaları müəyyən edir. Əsas bloklar: plugins (Gradle plaginlərinin qoşulması), repositories (asılılıq mənbələri: mavenCentral, google, jitpack). Kök build.gradle-da adətən android bloku olmur — o modullarda görünür. Project-level həmçinin bütün alt layihələrin ümumi konfiqurasiyası üçün subprojects blokunu ehtiva edə bilər, baxmayaraq ki, Convention Plugins daha üstündür.

Module-level build.gradle (məsələn, app/build.gradle) konkret modulu təsvir edir. Modul tətbiqdirsə, com.android.application plaginini tətbiq edir. Kitabxanadırsa — com.android.library. Module-level-də yerləşir: android bloku (compileSdk, defaultConfig, buildTypes, productFlavors), dependencies bloku (modulun asılılıqları) və test və quruluş konfiqurasiyası üçün isteğe bağlı bloklar. Module-level project-level-dən sonra icra olunur və ümumi parametrləri ləğv edə bilər.

AGP 8.0-dan etibarən kök build.gradle asılılıq versiyalarının mərkəzləşdirilmiş idarə edilməsi üçün version catalogs (libs.versions.toml) istifadə edə bilər. Version catalog — gradle/ kataloqunda versiyaları, kitabxanaları və plaginləri ehtiva edən fayldır. build.gradle-da asılılıqlar libs vasitəsilə qoşulur: implementation(libs.retrofit). Version catalogs yeni layihələr üçün məcburidir və üç və daha çox modulu olan bütün layihələr üçün tövsiyə olunur.

// settings.gradle.kts — layihənin kökü
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (layihə səviyyəsi)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (modul səviyyəsi)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy vs Kotlin DSL

Groovy — Gradle-in orijinal sintaksisi olan dinamik JVM dilidir. Groovy skriptləri (.gradle) dinamik tipizasiyadan istifadə edir: tipləri göstərməmək, dırnaq işarələrindən istifadə etmək və ya etməmək, tərtib mərhələsində mövcud olmayan metodları çağırmaq olar. Groovy-nin çevikliyi onun çatışmazlığıdır: IDE skriptin icrasından əvvəl sintaksis və tipləri yoxlaya bilmir, bu da səhv parametr adı və ya tip olduqda runtime xətalarına səbəb olur.

Kotlin DSL (.gradle.kts) Kotlin-in statik tipizasiyasından istifadə edir. IDE tipləri yoxlayır, avtomatik tamamlama vasitəsilə mövcud parametrləri təklif edir və redaktə mərhələsində xətaları göstərir. Kotlin DSL Konfiqurasiya mərhələsində daha yavaşdır (.kts fayllarının bayt koduna tərtib edilməsi səbəbindən), lakin Google performansı daim yaxşılaşdırır: AGP 8.5+ Gradle Configuration Cache və Caching Kotlin DSL compilation istifadə edir ki, bu da fərqi 1-2 saniyəyə endirir.

Google bütün yeni layihələr üçün Kotlin DSL-i və mövcud layihələrin tədricən miqrasiyasını tövsiyə edir. Groovy-dən Kotlin DSL-ə miqrasiya sadədir: dırnaqlar mötərizələrlə əvəz olunur, tiplər əlavə edilir, operatorlar funksiyalara çevrilir. Əksər kitabxanalar sənədlərdə Kotlin DSL nümunələri təqdim edir. Mürəkkəb hallar üçün (Custom Plugin, Task Graph) Kotlin DSL type-safe API təmin edir və Groovy-də yalnız runtime-da aşkar edilən xətalardan qoruyur. Version catalogs (libs.versions.toml) hər iki sintaksislə eyni işləyir.

Android bloku: tətbiqin konfiqurasiyası

compileSdk, minSdk və targetSdk

Android bloku — module-level build.gradle-in mərkəzi elementidir. Onun daxilində konfiqurasiya edilir: namespace (R və BuildConfig üçün), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Android blokunun bütün parametrləri yalnız Android modullarına tətbiq olunur. Modul kitabxanadırsa, tətbiq əvəzinə kitabxana plaginindən istifadə olunur və android blokunda applicationId olmur.

compileSdk — kodun tərtib edildiyi SDK versiyası. Ən son Android API-yə bərabər olmalıdır (yazı zamanı — 35). minSdk — dəstək üçün minimum API versiyası. targetSdk — tətbiqin yönəldiyi versiya (bu versiyanın davranış dəyişiklikləri tətbiq olunur). compileSdk və targetSdk arasındakı fərq: compileSdk mövcud API-ləri, targetSdk runtime davranışını müəyyən edir. Tövsiyə: compileSdk = ən son, targetSdk = ən son - 1 (yeni dəyişikliklərə uyğunlaşmanı sınamaq üçün).

compileOptions Java uyğunluğunu təyin edir: sourceCompatibility və targetCompatibility. AGP 8+ tərtib üçün Java 17+ tələb edir. packaging kitabxanalardan faylların daxil edilməsini idarə edir: META-INF münaqişələrinin həlli üçün exclude, merge, pickFirst. buildFeatures ViewBinding, DataBinding, Compose-u aktivləşdirir/deaktiv edir. aaptOptions resursların emalını konfiqurasiya edir: ignoreAssetsPattern, cruncherEnabled. Android blokunun hər bir elementi quruluşun müəyyən aspektini optimallaşdırır.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

Asılılıqların idarə edilməsi

BOM (Bill of Materials)

Asılılıqlar build.gradle-da layihəyə qoşulan kitabxana və modullardır. dependencies bloku android bloku ilə eyni səviyyədə yerləşir. Gradle bir neçə konfiqurasiyanı dəstəkləyir: implementation (kitabxana bu modulda mövcuddur, tranzitiv deyil), api (kitabxana asılı modullar üçün tranzitiv mövcuddur), compileOnly (yalnız tərtib üçün, APK-ya daxil edilmir), runtimeOnly (yalnız runtime-da), annotationProcessor / ksp (annotasiya emalçıları), testImplementation (yalnız testlər üçün), androidTestImplementation (yalnız instrumental testlər üçün).

AGP 8.0-dan etibarən Non-Transitive R classes — hər kitabxananın öz R sinfi var, bu da resurs münaqişələrinin qarşısını alır. dependencies blokunda düzgün konfiqurasiyalardan istifadə etmək vacibdir: implementation tranzitiv asılılıqları açıqlamır, bu da qurulmanı sürətləndirir. api açıqlayır — kitabxana başqa kitabxanadan tipləri ixrac etdikdə istifadə olunur (məsələn, Retrofit öz ictimai API-sində OkHttp tiplərindən istifadə edir).

Versiyaların idarə edilməsi üçün BOM (Bill of Materials) — kitabxanaların uyğun versiyalarını müəyyən edən quruluş faylından istifadə etmək tövsiyə olunur. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). BOM qoşulduqdan sonra yalnız kitabxana adını versiyasız göstərmək olar — BOM avtomatik olaraq uyğun versiyanı seçəcək. Bu, müxtəlif kitabxanaların tranzitiv asılılıqları arasındakı münaqişələri aradan qaldırır. BOM Firebase, Compose, Kotlin, Ktor, AndroidX üçün mövcuddur.

dependencies {
    // BOM — versiya idarəetməsi
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX və Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (BOM versiyaları)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Test
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

Çoxmodullu layihələrdə build.gradle

Çoxmodullu layihələrdə hər modulun öz build.gradle faylı var. Bir modulu digərinə qoşmaq üçün implementation(project(":module-name")) sintaksisindən istifadə olunur. Gradle konfiqurasiyası dəyişdikdə modulu avtomatik qurur. Çoxmodullu arxitektura qurulma müddətini yaxşılaşdırır (inkremental qurulma, paralellik) və məsuliyyəti funksional modullar, core modullar və kitabxanalar arasında bölür.

Çoxmodullu layihələrin əsas problemi — konfiqurasiyanın təkrarlanması. 10 modulun eyni minSdk, compileSdk və Compose asılılıqları varsa, bu müxtəlif build.gradle fayllarında 10 nüsxədir. Həll yolu — Convention Plugins (əvvəllər buildSrc). Convention Plugin — Kotlin dilində yazılmış, modullara tətbiq olunan Gradle plaginidir: plugins { id("myapp.android.library") }. Plugin ümumi konfiqurasiyanı ehtiva edir və dəyişikliklər dərhal bütün modullara tətbiq olunur.

Convention Plugins-in təşkili üçün layihənin kökündə build-logic/ kataloqundan istifadə olunur. O, settings.gradle-da includeBuild və Kotlin plaginlərini ehtiva edir. Convention Plugins layihələr arasında təkrar istifadə üçün maven depozitoriyasında dərc edilə bilər. Google Convention Plugins-i subprojects { } və apply from əvəz edən çoxmodullu layihələr üçün standart olaraq tövsiyə edir. Convention Plugins-ə keçid modulun build.gradle faylını 10-15 sətirə qədər qısaldır.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — Convention Plugin-dən sonra
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}