build.gradle: Android'de sözdizimi ve yapılandırması nedir

build.gradle nedir?

build.gradle, Groovy (.gradle uzantısı) veya Kotlin (.gradle.kts) dilinde yazılmış ve bir Android uygulamasının derlenmesinin tüm yönlerini yöneten bir derleme betiğidir. Gradle, Google tarafından 2013 yılında Android için standart olarak kabul edilen otomatik bir derleme sistemidir. build.gradle şunları açıklar: hangi eklentilerin uygulandığı (Android, Kotlin, kütüphaneler), hangi bağımlılıkların bağlandığı, hangi SDK sürümlerinin kullanıldığı, uygulamanın nasıl imzalanacağı ve nerede yayınlanacağı.

Derleme süreci üç aşamadan oluşur: Initialization (modül keşfi), Configuration (build.gradle betiklerinin yürütülmesi), Execution (görevlerin yürütülmesi). build.gradle, Gradle'ın görev grafiğini oluşturduğu Configuration aşamasında çalıştırılır. Bu noktada Build Variants belirlenir, bağımlılıklar hesaplanır ve görevler yapılandırılır. Önemli: build.gradle koddur, sadece yapılandırma değildir. İçinde koşullar, döngüler, metot çağrıları ve harici betikler kullanılabilir.

Gradle dosyaları modül kökünde (app/build.gradle) ve proje kökünde (build.gradle) saklanır. Ayrıca Gradle, apply from — harici Gradle betiklerinin dahil edilmesini destekler. Bu, tekrarlayan mantığın paylaşılan ayarlara sahip dosyalara çıkarılmasını sağlar. Convention Plugins'in (AGP 7+) ortaya çıkmasıyla apply from kullanımdan kalkmış sayılır — Convention Plugins, modüller arasında yapılandırmanın yeniden kullanılması için tip güvenli ve birleştirilebilir bir yol sağlar.

build.gradle'ın evrimi

2013'ten bu yana build.gradle sözdizimi önemli değişiklikler geçirdi: dinamik yapılandırmalara sahip Groovy'den derleme zamanı kontrollerine sahip Kotlin DSL'ye. AGP, sürüm 1.0'dan 8.7'ye (2025) evrildi. Önemli kilometre taşları: AGP 3.0 (Java 8 desugar, yeni variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (varsayılan olarak Kotlin DSL, Java 11 minimum), AGP 8.0 (geçişsiz R sınıfları, Kotlin'de derleme yapılandırması), AGP 8.7 (kapt yerine KSP, hızlı yapılandırma).

Project-level ve Module-level build.gradle

Project-level build.gradle (kök), tüm modüller için ortak olan eklentileri, depoları ve yapılandırmaları tanımlar. Ana bloklar: plugins (Gradle eklenti bildirimleri), repositories (bağımlılık kaynakları: mavenCentral, google, jitpack). Kök build.gradle genellikle android bloğuna sahip değildir — modüllerde görünür. Project-level, Convention Plugins tercih edilse de, tüm alt projelerin ortak yapılandırması için bir subprojects bloğu da içerebilir.

Module-level build.gradle (örn. app/build.gradle) belirli bir modülü tanımlar. Modül bir uygulamaysa com.android.application eklentisini uygular. Kütüphaneyse — com.android.library. Module-level şunları içerir: android bloğu (compileSdk, defaultConfig, buildTypes, productFlavors), dependencies bloğu (modül bağımlılıkları) ve isteğe bağlı olarak test ve paketleme yapılandırması için bloklar. Module-level, project-level'den sonra çalışır ve ortak ayarları geçersiz kılabilir.

AGP 8.0'den itibaren, kök build.gradle, merkezi bağımlılık sürüm yönetimi için version catalogs (libs.versions.toml) kullanabilir. version catalog, gradle/ dizininde sürümleri, kütüphaneleri ve eklentileri içeren bir dosyadır. build.gradle'da bağımlılıklar libs aracılığıyla bağlanır: implementation(libs.retrofit). version catalogs, yeni projeler için zorunludur ve üç veya daha fazla modülü olan tüm projeler için önerilir.

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

// build.gradle.kts (project-level)
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 (module-level)
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'ın orijinal sözdizimi olan dinamik bir JVM dilidir. Groovy betikleri (.gradle) dinamik tip kullanımı kullanır: tipler atlanabilir, tırnak işaretli veya işaretsiz dizeler kullanılabilir, derleme zamanında var olmayan metotlar çağrılabilir. Groovy'nin esnekliği aynı zamanda dezavantajıdır: IDE, betik yürütülene kadar sözdizimini ve tipleri doğrulayamaz ve bu da yanlış parametre adları veya tipleri nedeniyle çalışma zamanı hatalarına yol açar.

Kotlin DSL (.gradle.kts), Kotlin'in statik tip kullanımını kullanır. IDE tipleri doğrular, otomatik tamamlama yoluyla mevcut parametreleri önerir ve düzenleme sırasında hataları vurgular. Kotlin DSL, Configuration aşamasında daha yavaştır (.kts dosyalarını bayt koduna derlediği için), ancak Google performansı sürekli iyileştirir: AGP 8.5+, Gradle Configuration Cache ve Caching Kotlin DSL compilation kullanarak farkı 1-2 saniyeye düşürür.

Google, tüm yeni projeler için Kotlin DSL'yi ve mevcut projelerin kademeli olarak geçişini önerir. Groovy'den Kotlin DSL'ye geçiş basittir: tırnak işaretleri parantezlerle değiştirilir, tipler eklenir, operatörler fonksiyonlara dönüştürülür. Çoğu kütüphane, belgelerinde Kotlin DSL örnekleri sağlar. Karmaşık durumlar için (Custom Plugin, Task Graph), Kotlin DSL tip güvenli bir API sağlar ve Groovy'de yalnızca çalışma zamanında keşfedilen hataları önler. Version catalogs (libs.versions.toml) her iki sözdizimiyle de aynı şekilde çalışır.

android bloğu: uygulama yapılandırması

compileSdk, minSdk ve targetSdk

android bloğu, module-level build.gradle'ın merkezi öğesidir. İçinde şunlar yapılandırılır: namespace (R ve BuildConfig için), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. android bloğunun tüm parametreleri yalnızca Android modüllerine uygulanır. Modül bir kütüphaneyse, application yerine kütüphane eklentisi kullanılır ve android bloğunda applicationId bulunmaz.

compileSdk, kodun derlendiği SDK sürümüdür. En son Android API'sine eşit olmalıdır (yazım sırasında — 35). minSdk, desteklenen minimum API sürümüdür. targetSdk, uygulamanın hedeflediği sürümdür (bu sürümün davranışsal değişiklikleri uygulanır). compileSdk ve targetSdk arasındaki fark: compileSdk mevcut API'leri belirler, targetSdk çalışma zamanı davranışını belirler. Öneri: compileSdk = en son, targetSdk = en son - 1 (yeni değişikliklere uyum sağlamayı test etmek için).

compileOptions, Java uyumluluğunu ayarlar: sourceCompatibility ve targetCompatibility. AGP 8+, derleme için Java 17+ gerektirir. packaging, kütüphanelerden dosya dahil etmeyi yönetir: META-INF çakışmalarını çözmek için exclude, merge, pickFirst. buildFeatures, ViewBinding, DataBinding, Compose'u etkinleştirir/devre dışı bırakır. aaptOptions, kaynak işlemeyi yapılandırır: ignoreAssetsPattern, cruncherEnabled. android bloğunun her öğesi, derlemenin belirli bir yönünü optimize eder.

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

Bağımlılık yönetimi

BOM (Bill of Materials)

build.gradle'daki bağımlılıklar, projeye bağlı kütüphaneler ve modüllerdir. dependencies bloğu, android bloğuyla aynı seviyededir. Gradle birkaç yapılandırmayı destekler: implementation (kütüphane bu modülde kullanılabilir, geçişli değildir), api (kütüphane bağımlı modüllere geçişli olarak kullanılabilir), compileOnly (sadece derleme için, APK'ya dahil edilmez), runtimeOnly (sadece çalışma zamanında), annotationProcessor / ksp (ek açıklama işlemcileri), testImplementation (sadece testler için), androidTestImplementation (sadece araçlı testler için).

AGP 8.0'den itibaren, Geçişsiz R sınıfları — her kütüphanenin kendi R sınıfı vardır, bu da kaynak çakışmalarını önler. dependencies bloğunda doğru yapılandırmaları kullanmak önemlidir: implementation, geçişli bağımlılıkları açığa çıkarmaz, derlemeyi hızlandırır. api onları açığa çıkarır — bir kütüphane başka bir kütüphaneden türleri dışa aktardığında kullanılır (örneğin, Retrofit, genel API'sinde OkHttp türlerini kullanır).

Sürüm yönetimi için BOM (Bill of Materials) kullanılması önerilir — uyumlu kütüphane sürümlerini tanımlayan bir derleme dosyasıdır. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). BOM bağlandıktan sonra, sürüm olmadan yalnızca kütüphane adı belirtilebilir — BOM otomatik olarak uyumlu bir sürüm seçecektir. Bu, farklı kütüphanelerin geçişli bağımlılıkları arasındaki çakışmaları ortadan kaldırır. BOM'lar Firebase, Compose, Kotlin, Ktor, AndroidX için kullanılabilir.

dependencies {
    // BOM — sürüm yönetimi
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX ve 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 sürümleri)
    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")
}

Çok modüllü projelerde build.gradle

Çok modüllü projelerde, her modülün kendi build.gradle'ı vardır. Bir modülü diğerine bağlamak için implementation(project(":module-name")) sözdizimi kullanılır. Gradle, yapılandırması değiştiğinde modülü otomatik olarak yeniden oluşturur. Çok modüllü mimari, derleme süresini iyileştirir (artımlı derleme, paralellik) ve özellik modülleri, çekirdek modüller ve kütüphaneler arasındaki sorumlulukları ayırır.

Çok modüllü projelerin temel sorunu yapılandırma tekrarıdır. 10 modül aynı minSdk, compileSdk ve Compose bağımlılıklarına sahipse, bu farklı build.gradle dosyalarında 10 kopyadır. Çözüm Convention Plugins'dir (önceden buildSrc). Convention Plugin, Kotlin'de yazılmış ve modüllere uygulanan bir Gradle eklentisidir: plugins { id("myapp.android.library") }. Eklenti ortak yapılandırmayı içerir ve değişiklikler anında tüm modüllere uygulanır.

Convention Plugins'i düzenlemek için proje kökünde build-logic/ dizini kullanılır. settings.gradle'da includeBuild ve Kotlin eklentilerini içerir. Convention Plugins, projeler arasında yeniden kullanım için bir maven deposunda yayınlanabilir. Google, çok modüllü projeler için standart olarak Convention Plugins'i önerir ve subprojects { } ile apply from'un yerini alır. Convention Plugins'e geçiş, modülün build.gradle'ını 10-15 satıra düşürü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'den sonra
plugins {
    id("myapp.android.library")
}

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