compileSdkVersion: əsaslar, yeni API-lər və Gradle konfiqurasiyası

Android-də compileSdkVersion nədir?

compileSdkVersion — build.gradle-da kodun hansı Android SDK versiyasına qarşı kompilyasiya olunacağını göstərən tam parametrdir. android.* və ya androidx.* siniflərindən istifadə edən kod yazdıqda, kompilyator onları göstərilən compileSdk versiyasında mövcud olan API-lərlə yoxlayır. Əgər metod API 36-da ortaya çıxıbsa və compileSdk = 35-dirsə, kod kompilyasiya olunmayacaq. compileSdk = 36 olarsa — kod kompilyasiya olunacaq, lakin API 35 olan cihazda bu metodu yoxlamadan çağırmaq xətaya səbəb olacaq.

compileSdkVersion Android SDK Platform-dan yüklənir, SDK Manager vasitəsilə Android Studio-da quraşdırılır. Hər API Level-in öz platforması var: android-21, android-29, android-34, android-35, android-36. Platforma Kotlin/Java kompilyatorunun işlədiyi siniflər, metodlar və sabitlər dəstini — android.jar-ı ehtiva edir. Platforma quraşdırılmayıbsa, Gradle ilk kompilyasiyada sdkmanager vasitəsilə onu avtomatik yükləyəcək.

AGP (Android Gradle Plugin) versiyası 8.7+ Kotlin DSL-də compileSdk-nı android- prefiksi olmadan compileSdk = 36 kimi tam ədəd olaraq göstərməyi tövsiyə edir. compileSdk-nı həmçinin Groovy DSL-də compileSdkVersion 36 və ya SDK-nın ilkin versiyaları (developer previews) üçün compileSdkPreview vasitəsilə göstərmək olar. compileSdkPreview rəsmi buraxılışa qədər gələcək API Level-i test etmək üçün istifadə olunur.

// build.gradle.kts — compileSdkVersion konfiqurasiyası
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — son sabit API Level (Android 16)
    compileSdk = 36

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

// Alternativ olaraq: preview versiyaları üçün compileSdkPreview
// compileSdkPreview = "Baklava"

Nümunədə compileSdk = 36 Android 16 (Baklava)-nın bütün API-lərinə giriş verir. Android SDK Platform 36 SDK Manager-da quraşdırılmalıdır. "Baklava" adı ilə compileSdkPreview platformanın rəsmi buraxılışına qədər qeyri-sabit API-ləri test etmək üçün istifadə edilə bilər. Buraxılışdan sonra preview sabit compileSdk = 36 ilə əvəz olunur.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Üç API Level parametri build.gradle-da — compileSdkVersion, targetSdkVersion və minSdkVersion — tez-tez qarışdırılır. Hər biri uyğunluğun fərqli aspektinə cavabdehdir və onların dəyərləri compileSdk >= targetSdk >= minSdk qaydasına uyğun olmalıdır. minSdk — aşağı hədd: bu səviyyədən aşağı cihazlar tətbiqi görməyəcək. targetSdk — test nöqtəsi: behavioural changes bu səviyyəyə qədər aktivləşdirilir. compileSdk — yuxarı hədd: bu səviyyədən yuxarı API-lər kompilyator üçün əlçatan deyil.

Əsas praktiki qayda: compileSdk cihazlarda heç bir test olmadan yüksəldilə bilər. Bu, yalnız kompilyatora android.jar-ın yeni versiyasını verən təhlükəsiz əməliyyatdır. Yeganə risk — platformanın yeni versiyasında silinə bilən köhnəlmiş API-lərdir, lakin bu kompilyasiya mərhələsində aşkar edilir və asanlıqla düzəldilir. targetSdk-nın yüksəldilməsi isə tam QA dövrü tələb edir.

Niyə compileSdk targetSdk-dan yüksək ola bilər? Təsəvvür edin ki, Android 16 (API 36) kodda istifadə etmək istədiyiniz yeni API-lərlə çıxdı, lakin API 36-nın behavioural changes-ni hələ test etməmisiniz. Siz compileSdk = 36 (yeni API-lər əlçatandır), targetSdk = 35 (API 36-nın behavioural changes-i söndürülüb) təyin edirsiniz. Kod kompilyasiya olunacaq, SDK_INT yoxlamaları altında yeni metodlardan istifadə edəcək, API 36-nın behavioural changes-i isə tətbiqi pozmayacaq, çünki targetSdk = 35.

Düzgün kombinasiyaların nümunələri

compileSdk = 36, targetSdk = 36, minSdk = 26 — ən son API-lər və behavioural changes ilə tam uyğunluq, cihazların 85%-ni əhatə edir. compileSdk = 36, targetSdk = 34, minSdk = 26 — yeni API-lər əlçatandır, behavioural changes yalnız API 34-ə qədər. compileSdk = 35, targetSdk = 36 — düzgün deyil: compileSdk targetSdk-dan aşağıdır, API 36 əlçatan deyil, behavioural changes 36 isə aktivdir.

compileSdkVersion necə yeniləmək: addım-addım təlimat

compileSdkVersion-un yenilənməsi — Android layihəsində ən sadə və təhlükəsiz əməliyyatlardan biridir. targetSdk-dan fərqli olaraq, behavioural changes-nin uzun müddətli testini tələb etmir. Bununla belə, kompilyasiya xətalarından və köhnəlmə xəbərdarlıqlarından qaçmaq üçün bir neçə addım yerinə yetirilməlidir.

Addım 1 — yeni platformanı quraşdırın Android Studio-da SDK Manager vasitəsilə: Tools → SDK Manager → SDK Platforms → yeni API Level seçin. Platformanı quraşdırmasanız, Gradle onu avtomatik yükləməyə çalışacaq, lakin bu ilk kompilyasiyanı ləngidə bilər. Addım 2 — build.gradle-da compileSdk-nı yeni dəyərə dəyişin. Addım 3 — kompilyasiyanı icra edin (Build → Make Project) və kompilyasiya xətalarını düzəldin.

Addım 4 — köhnəlmiş API-ləri yoxlayın. compileSdk yüksəldildikdən sonra bəzi metodlar "removed in API X" qeydi ilə @Deprecated olaraq işarələnə bilər. Android Studio onları üstündən xətt çəkərək vurğulayır və xəbərdarlıq göstərir. Köhnəlmiş çağırışları yeni alternativlərlə əvəz edin. Əgər alternativ minSdk-dan yüksək API Level tələb edirsə, runtime yoxlaması əlavə edin. Addım 5 — dependencies yoxlayın: bəzi kitabxanalar müəyyən compileSdk versiyası tələb edə bilər. AGP 8.7+ compileSdk = 36 tövsiyə edir.

// compileSdk yüksəldilməsindən sonra: köhnəlmiş API-lərin dəyişdirilməsi
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // ƏVVƏL: köhnəlmiş metod (yeni API-də silinə bilər)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // API 36-da köhnələ bilər
    }

    // SONRA: yeni alternativ (əgər mövcuddursa)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // compileSdk 36-dan yeni API
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Yeni API nümunəsi
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

CompileSdkMigration sinfi düzgün miqrasiya nümunəsini göstərir. Köhnə memoryClass metodu yeni API-də silinə bilər — kompilyator xəta verəcək. Yeni alternativ getMemoryClassSafe yalnız API 36+-da mövcuddur, buna görə SDK_INT >= BAKLAVA yoxlaması altında çağırılır. Köhnə cihazlar üçün @Suppress("DEPRECATION") ilə fallback istifadə olunur.

Yeni API-lərlə iş: conditional checks və fallback

Yeni API-lər, compileSdkVersion-un yüksəldilməsi sayəsində əlçatan olan, minSdkVersion bu API Level-dən aşağı olduqda birbaşa çağırıla bilməz. Runtime yoxlaması olmadan tətbiq köhnə cihazlarda AbstractMethodError, NoSuchMethodError və ya VerifyError ilə çökəcək. Əsas qoruyucu mexanizm — Build.VERSION.SDK_INT yoxlaması ilə yeni API-nin yalnız kifayət qədər API Level-də çağırılması və köhnə versiyalar üçün fallback.

AndroidX bir çox yeni API-lərin backport-larını təmin edir ki, bu da aşağı compileSdk-da belə müasir metodlardan istifadə etməyə imkan verir. Məsələn, androidx.activity:activity-ktx:1.9.3-dən Activity Result API API 14-dən başlayaraq Android-in bütün versiyalarında işləyir. AndroidX-dən NotificationCompat köhnə API-lərdə müasir bildirişlərdən istifadə etməyə imkan verir. PhotoPicker API 34+-dan başlayaraq ActivityResultContracts.PickVisualMedia vasitəsilə əlçatandır.

// compileSdk 36 və minSdk 26 ilə yeni API-nin təhlükəsiz çağırılması
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: rənglə iş üçün yeni metod
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // compileSdk 36-dan yeni API — API 36+ tələb edir
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: köhnə API-lər üçün əl ilə formatlama
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport tələb olunmur — SDK_INT yoxlaması
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Activity-də istifadə
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

NewApiHelper sinfi köhnə versiyalar üçün fallback formatlaması ilə yeni Color.toArgbHexString API-nin (hipotetik API 36) təhlükəsiz çağırılmasını nümayiş etdirir. Əsas prinsip: compileSdk koddakı yeni metodları çağırmaq imkanı verir, lakin SDK_INT runtime yoxlaması köhnə cihazlarda çökmədən qoruyur. SDK_INT yoxlaması olmadan minSdk 26 və compileSdk 36 olan tətbiq Android 8-15-də çökəcək.

AGP (Android Gradle Plugin) və compileSdkVersion

Android Gradle Plugin (AGP) — Android tətbiqlərinin kompilyasiyası üçün əsas alətdir. Hər AGP versiyası müəyyən compileSdkVersion diapazonunu dəstəkləyir. AGP 8.7.x (2026-cı ildə buraxılıb) compileSdk >= 34 tələb edir və compileSdk = 36 tövsiyə edir. AGP 8.5.x compileSdk 33-35-i dəstəkləyir. compileSdk AGP üçün minimal səviyyədən aşağı olarsa, kompilyasiya "The SDK platform (X) is not supported by this version of the Android Gradle Plugin" xətası ilə başa çatacaq.

NDK (Native Development Kit) də compileSdkVersion ilə bağlıdır. Layihə NDK vasitəsilə C/C++-də nativ koddan istifadə edirsə, compileSdk başlıq fayllarının və kitabxanaların versiyasını müəyyən edir. NDK r27+ compileSdk 36 tövsiyə edir. .so faylları olan kitabxanalar üçün compileSdk Application.mk-də APP_MIN_SDK_VERSION vasitəsilə nativ kod üçün minimal API Level-ə təsir edir.

Gradle (7.6+) və Kotlin (2.0+) da compileSdk ilə uyğunluğa təsir edir. AGP 8.7+ Gradle 8.9+ və Kotlin 2.0+ tələb edir. compileSdk yüksəldilərkən AGP, Gradle və Kotlin-i ən son sabit versiyalara yeniləmək tövsiyə olunur. Uyğunluğu Android Gradle Plugin compatibility rəsmi cədvəlində yoxlayın.

compileSdk yüksəldilməsində tipik problemlər

compileSdkVersion yüksəldilməsində problemlər üç kateqoriyaya bölünür: compilation errors, deprecated warnings və runtime incompatibilities. Compilation errors — metodlar API-dən silinib və kod kompilyasiya olunmur. Deprecated warnings — metodlar @Deprecated işarələnib, kod xəbərdarlıqlarla kompilyasiya olunur. Runtime incompatibilities — yeni API-lər müəyyən funksionallıq üçün məcburidir və cihazda kifayət qədər API Level olmadıqda xətaya səbəb olur.

Birinci tipik problem — "Cannot resolve symbol X". Bu o deməkdir ki, sinif və ya metod SDK-nın yeni versiyasında ictimai API-dən silinib. Həll yolu: yeni platformada alternativ tapmaq və ya AndroidX ekvivalentindən istifadə etmək. Məsələn, AsyncTaskLoader sinfi API 28-də köhnəlmiş və daha yeni versiyalarda ictimai API-dən silinmişdir. Alternativ — Kotlin Coroutines və ya WorkManager.

İkinci problem — metod imzasının dəyişməsi. API-nin yeni versiyasında metod parametrlərin sayını və ya növlərini dəyişə bilər. Kotlin/Java kompilyatoru "None of the following functions can be called with the arguments supplied" xətası verir. Həll yolu: metod çağırışını yeni imzaya uyğun yeniləmək və ya köhnə cihazlar üçün SDK_INT yoxlaması ilə köhnə imzanı çağırmaq.

// compileSdk yüksəldilməsində problemlərin həlli
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problem: hasSystemFeature metodu API 36-da imzasını dəyişdi
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Yeni imza: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Köhnə imza: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problem: sinif silinib, AndroidX ekvivalentindən istifadə edirik
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // android.app.FragmentManager (silinib) əvəzinə istifadə edirik
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

CompileSdkProblemFixer sinfi tipik problemləri həll edir: dəyişdirilmiş hasSystemFeature imzası (API 36-da hipotetik dəyişiklik) SDK_INT yoxlaması ilə metodun düzgün versiyasını çağırmaqla idarə olunur. Silinmiş android.app.FragmentManager sinfi AndroidX ekvivalenti ilə əvəz edilmişdir. Alternativ olmayan köhnə çağırışlar üçün saxlanma səbəbi haqqında şərh ilə @Suppress("DEPRECATION") istifadə olunur.