compileSdkVersion: podstawy, nowe API i konfiguracja w Gradle

Czym jest compileSdkVersion w Android?

compileSdkVersion — parametr całkowity w build.gradle, który określa, względem której wersji Android SDK kompilować kod. Gdy piszesz kod używający klas z android.* lub androidx.*, kompilator sprawdza je z API dostępnymi w określonej wersji compileSdk. Jeśli metoda pojawiła się w API 36, a compileSdk = 35, kod się nie skompiluje. Jeśli compileSdk = 36 — kod się skompiluje, ale na urządzeniu z API 35 przy wywołaniu tej metody bez sprawdzenia wystąpi błąd.

compileSdkVersion jest pobierany z Android SDK Platform, zainstalowanej przez SDK Manager w Android Studio. Każdy API Level ma swoją platformę: android-21, android-29, android-34, android-35, android-36. Platforma zawiera android.jar — zestaw klas, metod i stałych, z którymi pracuje kompilator Kotlin/Java. Jeśli platforma nie jest zainstalowana, Gradle pobierze ją automatycznie przez sdkmanager przy pierwszej kompilacji.

AGP (Android Gradle Plugin) w wersji 8.7+ zaleca określanie compileSdk jako liczby całkowitej przez compileSdk = 36 w Kotlin DSL, bez prefiksu android-. compileSdk można również określić przez compileSdkVersion 36 w Groovy DSL lub compileSdkPreview dla wstępnych wersji SDK (developer previews). compileSdkPreview jest używany do testowania nadchodzących API Level przed oficjalnym wydaniem.

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

    // compileSdk = 36 — ostatni stabilny API Level (Android 16)
    compileSdk = 36

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

// Alternatywnie: compileSdkPreview dla wersji preview
// compileSdkPreview = "Baklava"

W przykładzie compileSdk = 36 daje dostęp do wszystkich API Android 16 (Baklava). Android SDK Platform 36 musi być zainstalowana w SDK Manager. compileSdkPreview z nazwą "Baklava" można użyć do testowania niestabilnych API przed oficjalnym wydaniem platformy. Po wydaniu preview jest zastępowany stabilnym compileSdk = 36.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Trzy parametry API Level w build.gradle — compileSdkVersion, targetSdkVersion i minSdkVersion — są często mylone. Każdy odpowiada za inny aspekt zgodności, a ich wartości powinny być zgodne z regułą compileSdk >= targetSdk >= minSdk. minSdk — dolna granica: urządzenia poniżej nie zobaczą aplikacji. targetSdk — punkt testowania: behavioural changes są włączane do tego poziomu. compileSdk — górna granica: API powyżej tego poziomu są niedostępne dla kompilatora.

Kluczowa praktyczna zasada: compileSdk można podnieść bez żadnego testowania na urządzeniach. To bezpieczna operacja, która jedynie daje kompilatorowi nową wersję android.jar. Jedynym ryzykiem są deprecated API, które mogą zostać usunięte w nowej wersji platformy, ale to wykrywa się na etapie kompilacji i łatwo naprawia. Podniesienie targetSdk, przeciwnie, wymaga pełnego cyklu QA.

Dlaczego compileSdk może być wyższy niż targetSdk? Wyobraź sobie, że wyszła Android 16 (API 36) z nowymi API, których chcesz użyć w kodzie, ale behavioural changes API 36 jeszcze nie testowałeś. Ustawiasz compileSdk = 36 (nowe API dostępne), targetSdk = 35 (behavioural changes API 36 wyłączone). Kod się skompiluje, będzie używać nowych metod pod SDK_INT-sprawdzeniami, a behavioural changes API 36 nie zepsują aplikacji, ponieważ targetSdk = 35.

Przykłady poprawnych kombinacji

compileSdk = 36, targetSdk = 36, minSdk = 26 — pełna zgodność z najnowszymi API i behavioural changes, zasięg 85% urządzeń. compileSdk = 36, targetSdk = 34, minSdk = 26 — nowe API dostępne, behavioural changes tylko do API 34. compileSdk = 35, targetSdk = 36 — niepoprawne: compileSdk niższy niż targetSdk, API 36 niedostępne, mimo że behavioural changes 36 są aktywne.

Jak aktualizować compileSdkVersion: przewodnik krok po kroku

Aktualizacja compileSdkVersion — jedna z najprostszych i najbezpieczniejszych operacji w projekcie Android. W przeciwieństwie do targetSdk, nie wymaga długiego testowania behavioural changes. Jednak jest kilka kroków, które należy wykonać, aby uniknąć błędów kompilacji i ostrzeżeń o deprecation.

Krok 1 — zainstaluj nową platformę przez SDK Manager w Android Studio: Tools → SDK Manager → SDK Platforms → wybierz nowy API Level. Jeśli nie zainstalujesz platformy, Gradle spróbuje pobrać ją automatycznie, ale może to spowolnić pierwszą kompilację. Krok 2 — zmień compileSdk w build.gradle na nową wartość. Krok 3 — wykonaj kompilację (Build → Make Project) i napraw błędy kompilacji.

Krok 4 — sprawdź deprecated API. Po podniesieniu compileSdk niektóre metody mogą być oznaczone @Deprecated z adnotacją "removed in API X". Android Studio podświetla je przekreśleniem i wyświetla warning. Zastąp deprecated-wywołania nowymi alternatywami. Jeśli alternatywa wymaga API Level wyższego niż minSdk, dodaj runtime-sprawdzenie. Krok 5 — sprawdź dependencies: niektóre biblioteki mogą wymagać określonej wersji compileSdk. AGP 8.7+ zaleca compileSdk = 36.

// Po podniesieniu compileSdk: zastąpienie deprecated API
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 {

    // PRZED: deprecated metoda (może zostać usunięta w nowym API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Może być deprecated w API 36
    }

    // PO: nowa alternatywa (jeśli dostępna)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nowe API z compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Przykład nowego API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Klasa CompileSdkMigration pokazuje poprawny wzorzec migracji. Stara metoda memoryClass może zostać usunięta w nowym API — kompilator zgłosi błąd. Nowa alternatywa getMemoryClassSafe jest dostępna tylko na API 36+, dlatego jest wywoływana pod sprawdzeniem SDK_INT >= BAKLAVA. Dla starych urządzeń używany jest fallback z @Suppress("DEPRECATION").

Praca z nowymi API: conditional checks i fallback

Nowe API, dostępne dzięki podniesieniu compileSdkVersion, nie mogą być wywoływane bezpośrednio, jeśli minSdkVersion jest niższy niż ten API Level. Bez runtime-sprawdzenia aplikacja padnie z AbstractMethodError, NoSuchMethodError lub VerifyError na starych urządzeniach. Głównym mechanizmem ochronnym jest sprawdzenie Build.VERSION.SDK_INT z wywołaniem nowego API tylko przy wystarczającym API Level i fallback dla starych wersji.

AndroidX zapewnia backporty wielu nowych API, co pozwala korzystać z nowoczesnych metod nawet przy niskim compileSdk. Na przykład Activity Result API z androidx.activity:activity-ktx:1.9.3 działa na wszystkich wersjach Androida począwszy od API 14. NotificationCompat z AndroidX pozwala używać nowoczesnych powiadomień na starych API. PhotoPicker jest dostępny przez ActivityResultContracts.PickVisualMedia począwszy od API 34+.

// Bezpieczne wywołanie nowego API z compileSdk 36 i minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: nowa metoda pracy z kolorem
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nowe API z compileSdk 36 — wymaga API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: ręczne formatowanie dla starych API
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport nie jest wymagany — sprawdzenie SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Użycie w Activity
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")
    }
}

Klasa NewApiHelper demonstruje bezpieczne wywołanie nowego API Color.toArgbHexString (hipotetyczne API 36) z fallback-formatowaniem dla starych wersji. Kluczowa zasada: compileSdk daje dostęp do wywołania nowych metod w kodzie, ale runtime-sprawdzenie SDK_INT chroni przed crash'em na starych urządzeniach. Bez sprawdzenia SDK_INT aplikacja z minSdk 26 i compileSdk 36 będzie padać na Android 8-15.

AGP (Android Gradle Plugin) i compileSdkVersion

Android Gradle Plugin (AGP) — to główne narzędzie kompilacji aplikacji Android. Każda wersja AGP obsługuje określony zakres compileSdkVersion. AGP 8.7.x (wydany w 2026 roku) wymaga compileSdk >= 34 i zaleca compileSdk = 36. AGP 8.5.x obsługuje compileSdk 33-35. Jeśli compileSdk jest niższy niż minimalny dla AGP, kompilacja zakończy się błędem "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) jest również powiązany z compileSdkVersion. Jeśli projekt używa natywnego kodu w C/C++ przez NDK, compileSdk określa wersję plików nagłówkowych i bibliotek. NDK r27+ zaleca compileSdk 36. Dla bibliotek z plikami .so compileSdk wpływa na minimalny API Level dla kodu natywnego przez APP_MIN_SDK_VERSION w Application.mk.

Gradle (7.6+) i Kotlin (2.0+) również wpływają na zgodność z compileSdk. AGP 8.7+ wymaga Gradle 8.9+ i Kotlin 2.0+. Przy podnoszeniu compileSdk zaleca się zaktualizowanie AGP, Gradle i Kotlin do najnowszych stabilnych wersji. Sprawdź zgodność w oficjalnej tabeli Android Gradle Plugin compatibility.

Typowe problemy przy podnoszeniu compileSdk

Problemy przy podnoszeniu compileSdkVersion dzielą się na trzy kategorie: compilation errors, deprecated warnings i runtime incompatibilities. Compilation errors — metody usunięte z API i kod się nie kompiluje. Deprecated warnings — metody oznaczone @Deprecated, kod kompiluje się z ostrzeżeniami. Runtime incompatibilities — nowe API są obowiązkowe dla określonej funkcjonalności i powodują błąd przy niewystarczającym API Level na urządzeniu.

Pierwszy typowy problem — "Cannot resolve symbol X". Oznacza to, że klasa lub metoda została usunięta z public API w nowej wersji SDK. Rozwiązanie: znaleźć alternatywę na nowej platformie lub użyć AndroidX-ekwiwalentu. Na przykład klasa AsyncTaskLoader była deprecated w API 28 i usunięta z public API w nowszych wersjach. Alternatywa — Kotlin Coroutines lub WorkManager.

Drugi problem — zmiana sygnatury metody. W nowej wersji API metoda mogła zmienić liczbę lub typy parametrów. Kompilator Kotlin/Java zgłasza błąd "None of the following functions can be called with the arguments supplied". Rozwiązanie: zaktualizować wywołanie metody pod nową sygnaturę lub dodać sprawdzenie SDK_INT z wywołaniem starej sygnatury dla starych urządzeń.

// Rozwiązywanie problemów przy podnoszeniu compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problem: metoda hasSystemFeature zmieniła sygnaturę w API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nowa sygnatura: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Stara sygnatura: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problem: klasa usunięta, używamy AndroidX ekwiwalentu
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Zamiast android.app.FragmentManager (usunięty) używamy
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Klasa CompileSdkProblemFixer rozwiązuje typowe problemy: zmieniona sygnatura hasSystemFeature (hipotetyczna zmiana w API 36) jest obsługiwana przez SDK_INT-sprawdzenie z wywołaniem poprawnej wersji metody. Usunięta klasa android.app.FragmentManager została zastąpiona AndroidX-ekwiwalentem. Dla starych wywołań, gdzie nie ma alternatywy, używane jest @Suppress("DEPRECATION") z komentarzem o przyczynie zachowania.