compileSdkVersion: temeller, yeni API'ler ve Gradle'da yapılandırma

Android'de compileSdkVersion nedir?

compileSdkVersion, build.gradle'da kodun hangi Android SDK sürümüne karşı derleneceğini belirten bir tamsayı parametresidir. android.* veya androidx.* sınıflarını kullanarak kod yazdığınızda, derleyici bunları belirtilen compileSdk sürümünde bulunan API'lerle karşılaştırır. Bir yöntem API 36'da tanıtıldıysa ve compileSdk = 35 ise, kod derlenmez. compileSdk = 36 ise, kod derlenir, ancak kontrol yapılmadan API 35'e sahip bir cihazda bu yöntemi çağırmak çökmeye neden olur.

compileSdkVersion, Android Studio'da SDK Manager aracılığıyla yüklenen Android SDK Platformu'ndan yüklenir. Her API Düzeyinin kendi platformu vardır: android-21, android-29, android-34, android-35, android-36. Platform, Kotlin/Java derleyicisinin kullandığı sınıflar, yöntemler ve sabitler kümesi olan android.jar'ı içerir. Platform yüklü değilse, Gradle ilk derlemede sdkmanager aracılığıyla otomatik olarak indirecektir.

AGP (Android Gradle Plugin) sürüm 8.7+, Kotlin DSL'de android- öneki olmadan compileSdk = 36 olarak compileSdk'nin bir tamsayı olarak belirtilmesini önerir. compileSdk, Groovy DSL'de compileSdkVersion 36 aracılığıyla veya ön sürüm SDK sürümleri (geliştirici önizlemeleri) için compileSdkPreview aracılığıyla da ayarlanabilir. compileSdkPreview, resmi sürümden önce yaklaşan API Düzeylerini test etmek için kullanılır.

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

    // compileSdk = 36 — en son kararlı API Düzeyi (Android 16)
    compileSdk = 36

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

// Alternatif: önizleme sürümleri için compileSdkPreview
// compileSdkPreview = "Baklava"

Örnekte, compileSdk = 36 tüm Android 16 (Baklava) API'lerine erişim sağlar. Android SDK Platform 36, SDK Manager'da yüklü olmalıdır. "Baklava" adıyla compileSdkPreview, resmi platform sürümünden önce kararsız API'leri test etmek için kullanılabilir. Sürümden sonra, önizleme kararlı compileSdk = 36 ile değiştirilir.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

build.gradle'daki üç API Düzeyi parametresi — compileSdkVersion, targetSdkVersion ve minSdkVersion — sıklıkla karıştırılır. Her biri uyumluluğun farklı bir yönünden sorumludur ve değerleri compileSdk >= targetSdk >= minSdk kuralına uymalıdır. minSdk alt sınırdır: bunun altındaki cihazlar uygulamayı görmez. targetSdk test noktasıdır: davranışsal değişiklikler bu düzeye kadar etkinleştirilir. compileSdk tavandır: bu düzeyin üzerindeki API'ler derleyici için kullanılamaz.

Temel pratik kural: compileSdk herhangi bir cihaz testi olmadan yükseltilebilir. Bu, derleyiciye yalnızca yeni bir android.jar sürümü sağlayan güvenli bir işlemdir. Tek risk, yeni platform sürümünde kaldırılabilecek kullanımdan kaldırılmış API'lerdir, ancak bu derleme zamanında tespit edilir ve kolayca düzeltilir. Öte yandan, targetSdk'yi yükseltmek tam bir QA döngüsü gerektirir.

compileSdk neden targetSdk'den daha yüksek olabilir? Android 16'nın (API 36) kodda kullanmak istediğiniz yeni API'lerle yayınlandığını, ancak API 36'nın davranışsal değişikliklerini henüz test etmediğinizi hayal edin. compileSdk = 36 (yeni API'ler mevcut), targetSdk = 35 (API 36 davranışsal değişiklikleri devre dışı) olarak ayarlarsınız. Kod derlenir, SDK_INT kontrolleri altında yeni yöntemleri kullanır ve targetSdk = 35 olduğu için API 36'nın davranışsal değişiklikleri uygulamayı bozmaz.

Doğru kombinasyon örnekleri

compileSdk = 36, targetSdk = 36, minSdk = 26 — en son API'ler ve davranışsal değişikliklerle tam uyumluluk, cihazların %85'ini kapsar. compileSdk = 36, targetSdk = 34, minSdk = 26 — yeni API'ler mevcut, davranışsal değişiklikler yalnızca API 34'e kadar. compileSdk = 35, targetSdk = 36 — yanlış: compileSdk targetSdk'den düşük, API 36 kullanılamazken 36'nın davranışsal değişiklikleri aktif.

compileSdkVersion nasıl güncellenir: adım adım kılavuz

compileSdkVersion'ı güncellemek bir Android projesindeki en basit ve en güvenli işlemlerden biridir. targetSdk'nin aksine, davranışsal değişikliklerin kapsamlı testini gerektirmez. Ancak, derleme hatalarından ve kullanımdan kaldırma uyarılarından kaçınmak için izlenmesi gereken birkaç adım vardır.

Adım 1 — Android Studio'da SDK Manager aracılığıyla yeni platformu yükleyin: Tools → SDK Manager → SDK Platforms → yeni API Düzeyini seçin. Platformu yüklemezseniz, Gradle otomatik olarak indirmeye çalışır, ancak bu ilk derlemeyi yavaşlatabilir. Adım 2 — build.gradle'daki compileSdk değerini yeni değerle değiştirin. Adım 3 — derleyin (Build → Make Project) ve derleme hatalarını düzeltin.

Adım 4 — kullanımdan kaldırılmış API'leri kontrol edin. compileSdk'yi yükselttikten sonra, bazı yöntemler "removed in API X" notuyla @Deprecated olarak işaretlenebilir. Android Studio bunları üstü çizili olarak vurgular ve bir uyarı gösterir. Kullanımdan kaldırılmış çağrıları yeni alternatiflerle değiştirin. Alternatif, minSdk'den daha yüksek bir API Düzeyi gerektiriyorsa, bir çalışma zamanı kontrolü ekleyin. Adım 5 — bağımlılıkları kontrol edin: bazı kitaplıklar belirli bir compileSdk sürümü gerektirebilir. AGP 8.7+ compileSdk = 36 önerir.

// compileSdk yükselttikten sonra: kullanımdan kaldırılmış API'leri değiştirme
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 {

    // ÖNCE: kullanımdan kaldırılmış yöntem (yeni API'de kaldırılabilir)
    @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 kullanımdan kaldırılabilir
    }

    // SONRA: yeni alternatif (varsa)
    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 örneği
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

CompileSdkMigration sınıfı doğru geçiş modelini gösterir. Eski yöntem memoryClass yeni API'de kaldırılabilir — derleyici bir hata verecektir. Yeni alternatif getMemoryClassSafe yalnızca API 36+'da kullanılabilir, bu nedenle SDK_INT >= BAKLAVA kontrolü altında çağrılır. Eski cihazlar için @Suppress("DEPRECATION") ile bir geri dönüş kullanılır.

Yeni API'lerle çalışma: koşullu kontroller ve geri dönüş

Yeni API'ler compileSdkVersion yükseltmesiyle kullanılabilir hale gelir, ancak minSdkVersion bu API Düzeyinden düşükse doğrudan çağrılamaz. Çalışma zamanı kontrolü olmadan, uygulama eski cihazlarda AbstractMethodError, NoSuchMethodError veya VerifyError ile çöker. Birincil koruma mekanizması, Build.VERSION.SDK_INT'i kontrol etmek, yeni API'yi yalnızca API Düzeyi yeterli olduğunda çağırmak ve eski sürümler için bir geri dönüş sağlamaktır.

AndroidX, düşük bir compileSdk ile bile modern yöntemlerin kullanılmasına izin vererek birçok yeni API için geriye dönük uyumluluk sağlar. Örneğin, androidx.activity:activity-ktx:1.9.3'ten Activity Result API, API 14'ten başlayarak tüm Android sürümlerinde çalışır. AndroidX'ten NotificationCompat, eski API'lerde modern bildirimlere olanak tanır. PhotoPicker, API 34+'tan başlayarak ActivityResultContracts.PickVisualMedia aracılığıyla kullanılabilir.

// compileSdk 36 ve minSdk 26 ile yeni API'nin güvenli çağrısı
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: renkle çalışmak için yeni yöntem
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // compileSdk 36'dan yeni API — API 36+ gerektirir
            return Color.toArgbHexString(colorInt)
        }
        // Geri dönüş: eski API'ler için manuel biçimlendirme
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: geriye dönük uyumluluk gerekmez — SDK_INT kontrolü
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Activity'de kullanım
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 sınıfı, eski sürümler için geri dönüş biçimlendirmesiyle yeni API Color.toArgbHexString (varsayımsal API 36) çağrısının güvenli bir şekilde yapıldığını gösterir. Temel ilke: compileSdk, kodda yeni yöntemleri çağırmak için erişim sağlar, ancak çalışma zamanı SDK_INT kontrolü eski cihazlarda çökmelere karşı korur. SDK_INT kontrolü olmadan, minSdk 26 ve compileSdk 36 olan bir uygulama Android 8-15'te çöker.

AGP (Android Gradle Plugin) ve compileSdkVersion

Android Gradle Plugin (AGP), Android uygulamaları için birincil derleme aracıdır. Her AGP sürümü, belirli bir compileSdkVersion aralığını destekler. AGP 8.7.x (2026'da yayınlandı) compileSdk >= 34 gerektirir ve compileSdk = 36 önerir. AGP 8.5.x, compileSdk 33-35'i destekler. compileSdk, AGP için minimum değerin altındaysa, derleme şu hatayla başarısız olur: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) de compileSdkVersion'a bağlıdır. Projeniz NDK aracılığıyla C/C++ yerel kodu kullanıyorsa, compileSdk başlık dosyalarının ve kitaplıkların sürümünü belirler. NDK r27+ compileSdk 36 önerir. .so dosyalarına sahip kitaplıklar için compileSdk, Application.mk'deki APP_MIN_SDK_VERSION aracılığıyla yerel kod için minimum API Düzeyini etkiler.

Gradle (7.6+) ve Kotlin (2.0+) da compileSdk uyumluluğunu etkiler. AGP 8.7+, Gradle 8.9+ ve Kotlin 2.0+ gerektirir. compileSdk'yi yükseltirken AGP, Gradle ve Kotlin'in en son kararlı sürümlere güncellenmesi önerilir. Resmi Android Gradle Plugin uyumluluk tablosunda uyumluluğu kontrol edin.

compileSdk yükseltirken yaygın sorunlar

compileSdkVersion yükseltirken sorunlar üç kategoriye ayrılır: derleme hataları, kullanımdan kaldırma uyarıları ve çalışma zamanı uyumsuzlukları. Derleme hataları — yöntemler API'den kaldırılır ve kod derlenmez. Kullanımdan kaldırma uyarıları — yöntemler @Deprecated olarak işaretlenir, kod uyarılarla derlenir. Çalışma zamanı uyumsuzlukları — yeni API'ler belirli işlevler için gereklidir ve cihazdaki API Düzeyi yetersizse hatalara neden olur.

İlk yaygın sorun — "Cannot resolve symbol X". Bu, bir sınıfın veya yöntemin yeni SDK sürümünde genel API'den kaldırıldığı anlamına gelir. Çözüm: yeni platformda bir alternatif bulun veya bir AndroidX eşdeğeri kullanın. Örneğin, AsyncTaskLoader sınıfı API 28'de kullanımdan kaldırıldı ve daha yeni sürümlerde genel API'den kaldırıldı. Alternatifler arasında Kotlin Coroutines veya WorkManager bulunur.

İkinci sorun — yöntem imzası değişikliği. Yeni API sürümünde, bir yöntem parametrelerinin sayısını veya türlerini değiştirmiş olabilir. Kotlin/Java derleyicisi bir hata verir: "None of the following functions can be called with the arguments supplied". Çözüm: yöntem çağrısını yeni imzayla eşleşecek şekilde güncelleyin veya eski cihazlar için eski imza çağrısıyla bir SDK_INT kontrolü ekleyin.

// compileSdk yükseltirken sorunları çözme
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Sorun: hasSystemFeature yöntemi API 36'da imza değiştirdi
    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 {
            // Eski imza: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Sorun: sınıf kaldırıldı, AndroidX eşdeğeri kullanın
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // android.app.FragmentManager (kaldırıldı) yerine kullanın
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

CompileSdkProblemFixer sınıfı yaygın sorunları çözer: hasSystemFeature'in değiştirilmiş imzası (API 36'daki varsayımsal değişiklik), yöntemin doğru sürümünü çağıran bir SDK_INT kontrolü aracılığıyla işlenir. Kaldırılan sınıf android.app.FragmentManager, AndroidX eşdeğeri ile değiştirilir. Alternatifi olmayan eski çağrılar için, @Suppress("DEPRECATION"), saklama nedenini açıklayan bir yorumla birlikte kullanılır.