compileSdkVersion: základy, nová API a nastavení v Gradle

Co je compileSdkVersion v Androidu?

compileSdkVersion — celočíselný parametr v build.gradle, který určuje, vůči které verzi Android SDK se má kód kompilovat. Když píšete kód používající třídy z android.* nebo androidx.*, kompilátor je kontroluje s API dostupnými v určené verzi compileSdk. Pokud se metoda objevila v API 36 a compileSdk = 35, kód se nezkompiluje. Pokud compileSdk = 36 — kód se zkompiluje, ale na zařízení s API 35 při volání této metody bez kontroly dojde k chybě.

compileSdkVersion se načítá z Android SDK Platform, nainstalované přes SDK Manager v Android Studio. Každá úroveň API Level má svou platformu: android-21, android-29, android-34, android-35, android-36. Platforma obsahuje android.jar — sadu tříd, metod a konstant, se kterými pracuje kompilátor Kotlin/Java. Pokud platforma není nainstalována, Gradle ji automaticky stáhne přes sdkmanager při prvním sestavení.

AGP (Android Gradle Plugin) verze 8.7+ doporučuje uvádět compileSdk jako celé číslo pomocí compileSdk = 36 v Kotlin DSL, bez předpony android-. compileSdk lze také uvést pomocí compileSdkVersion 36 v Groovy DSL nebo compileSdkPreview pro předběžné verze SDK (developer previews). compileSdkPreview se používá pro testování nadcházejících úrovní API Level před oficiálním vydáním.

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

    // compileSdk = 36 — poslední stabilní API Level (Android 16)
    compileSdk = 36

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

// Alternativně: compileSdkPreview pro předběžné verze
// compileSdkPreview = "Baklava"

V příkladu compileSdk = 36 poskytuje přístup ke všem API Android 16 (Baklava). Android SDK Platform 36 musí být nainstalována v SDK Manager. compileSdkPreview s názvem "Baklava" lze použít pro testování nestabilních API před oficiálním vydáním platformy. Po vydání je preview nahrazeno stabilním compileSdk = 36.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Tři parametry úrovně API Level v build.gradle — compileSdkVersion, targetSdkVersion a minSdkVersion — jsou často zaměňovány. Každý je zodpovědný za jiný aspekt kompatibility a jejich hodnoty musí být sladěny podle pravidla compileSdk >= targetSdk >= minSdk. minSdk — spodní hranice: zařízení pod ní aplikaci neuvidí. targetSdk — testovací bod: behavioural changes se zapínají do této úrovně. compileSdk — strop: API nad touto úrovní nejsou pro kompilátor dostupná.

Klíčové praktické pravidlo: compileSdk lze zvýšit bez jakéhokoli testování na zařízeních. Jedná se o bezpečnou operaci, která pouze poskytuje kompilátoru novou verzi android.jar. Jediné riziko — deprecated API, která mohou být odstraněna v nové verzi platformy, ale to je zjištěno ve fázi kompilace a snadno opravitelné. Zvýšení targetSdk naopak vyžaduje úplný QA cyklus.

Proč může být compileSdk vyšší než targetSdk? Představte si, že vyšel Android 16 (API 36) s novými API, která chcete v kódu používat, ale behavioural changes API 36 jste ještě netestovali. Nastavíte compileSdk = 36 (nová API dostupná), targetSdk = 35 (behavioural changes API 36 vypnuté). Kód se zkompiluje, bude používat nové metody pod kontrolami SDK_INT a behavioural changes API 36 aplikaci nerozbijí, protože targetSdk = 35.

Příklady správných kombinací

compileSdk = 36, targetSdk = 36, minSdk = 26 — plná kompatibilita s nejnovějšími API a behavioural changes, pokrytí 85 % zařízení. compileSdk = 36, targetSdk = 34, minSdk = 26 — nová API dostupná, behavioural changes pouze do API 34. compileSdk = 35, targetSdk = 36 — nesprávné: compileSdk nižší než targetSdk, API 36 nedostupná, i když behavioural changes 36 jsou aktivní.

Jak aktualizovat compileSdkVersion: průvodce krok za krokem

Aktualizace compileSdkVersion — jedna z nejjednodušších a nejbezpečnějších operací v Android projektu. Na rozdíl od targetSdk nevyžaduje dlouhé testování behavioural changes. Je však třeba provést několik kroků, aby se předešlo chybám kompilace a varováním o zastaralosti.

Krok 1 — nainstalujte novou platformu přes SDK Manager v Android Studio: Tools → SDK Manager → SDK Platforms → vyberte novou úroveň API Level. Pokud platformu nenainstalujete, Gradle se ji pokusí automaticky stáhnout, ale to může zpomalit první sestavení. Krok 2 — změňte compileSdk v build.gradle na novou hodnotu. Krok 3 — proveďte sestavení (Build → Make Project) a opravte chyby kompilace.

Krok 4 — zkontrolujte deprecated API. Po zvýšení compileSdk mohou být některé metody označeny @Deprecated s poznámkou "removed in API X". Android Studio je zvýrazní přeškrtnutím a zobrazí varování. Nahraďte zastaralá volání novými alternativami. Pokud alternativa vyžaduje vyšší úroveň API Level než minSdk, přidejte runtime kontrolu. Krok 5 — zkontrolujte dependencies: některé knihovny mohou vyžadovat určitou verzi compileSdk. AGP 8.7+ doporučuje compileSdk = 36.

// Po zvýšení compileSdk: nahrazení 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 {

    // PŘED: deprecated metoda (může být odstraněna v novém API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Může být deprecated v API 36
    }

    // PO: nová alternativa (pokud je k dispozici)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nové API z compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Příklad nového API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Třída CompileSdkMigration ukazuje správný migrační vzor. Stará metoda memoryClass může být v novém API odstraněna — kompilátor ohlásí chybu. Nová alternativa getMemoryClassSafe je dostupná pouze na API 36+, proto je volána pod kontrolou SDK_INT >= BAKLAVA. Pro stará zařízení se používá fallback s @Suppress("DEPRECATION").

Práce s novými API: podmíněné kontroly a fallback

Nová API, dostupná díky zvýšení compileSdkVersion, nelze přímo volat, pokud je minSdkVersion nižší než tato úroveň API Level. Bez runtime kontroly aplikace spadne s AbstractMethodError, NoSuchMethodError nebo VerifyError na starých zařízeních. Hlavní ochranný mechanismus — kontrola Build.VERSION.SDK_INT s voláním nového API pouze při dostatečné úrovni API Level a fallback pro staré verze.

AndroidX poskytuje backporty mnoha nových API, což umožňuje používat moderní metody i při nízkém compileSdk. Například Activity Result API z androidx.activity:activity-ktx:1.9.3 funguje na všech verzích Androidu od API 14. NotificationCompat z AndroidX umožňuje používat moderní oznámení na starých API. PhotoPicker je dostupný přes ActivityResultContracts.PickVisualMedia od API 34+.

// Bezpečné volání nového API s compileSdk 36 a 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+: nová metoda pro práci s barvou
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nové API z compileSdk 36 — vyžaduje API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: ruční formátování pro stará API
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport není vyžadován — kontrola SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Použití v 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")
    }
}

Třída NewApiHelper demonstruje bezpečné volání nového API Color.toArgbHexString (hypotetické API 36) s fallback formátováním pro staré verze. Klíčový princip: compileSdk poskytuje přístup k volání nových metod v kódu, ale runtime kontrola SDK_INT chrání před pádem na starých zařízeních. Bez kontroly SDK_INT aplikace s minSdk 26 a compileSdk 36 spadne na Android 8-15.

AGP (Android Gradle Plugin) a compileSdkVersion

Android Gradle Plugin (AGP) — hlavní nástroj pro sestavování Android aplikací. Každá verze AGP podporuje určitý rozsah compileSdkVersion. AGP 8.7.x (vydáno v roce 2026) vyžaduje compileSdk >= 34 a doporučuje compileSdk = 36. AGP 8.5.x podporuje compileSdk 33-35. Pokud je compileSdk nižší než minimum pro AGP, sestavení skončí chybou "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) je také vázán na compileSdkVersion. Pokud projekt používá nativní kód v C/C++ přes NDK, compileSdk určuje verzi hlavičkových souborů a knihoven. NDK r27+ doporučuje compileSdk 36. Pro knihovny se soubory .so compileSdk ovlivňuje minimální úroveň API Level pro nativní kód přes APP_MIN_SDK_VERSION v Application.mk.

Gradle (7.6+) a Kotlin (2.0+) také ovlivňují kompatibilitu s compileSdk. AGP 8.7+ vyžaduje Gradle 8.9+ a Kotlin 2.0+. Při zvyšování compileSdk se doporučuje aktualizovat AGP, Gradle a Kotlin na nejnovější stabilní verze. Zkontrolujte kompatibilitu v oficiální tabulce Android Gradle Plugin compatibility.

Typické problémy při zvyšování compileSdk

Problémy při zvyšování compileSdkVersion se dělí do tří kategorií: compilation errors, deprecated warnings a runtime incompatibilities. Compilation errors — metody odstraněné z API a kód se nekompiluje. Deprecated warnings — metody označené @Deprecated, kód se kompiluje s varováními. Runtime incompatibilities — nová API jsou povinná pro určitou funkcionalitu a způsobují chybu při nedostatečné úrovni API Level na zařízení.

První typický problém — "Cannot resolve symbol X". To znamená, že třída nebo metoda byla odstraněna z veřejného API v nové verzi SDK. Řešení: najít alternativu na nové platformě nebo použít AndroidX ekvivalent. Například třída AsyncTaskLoader byla deprecated v API 28 a odstraněna z veřejného API v novějších verzích. Alternativa — Kotlin Coroutines nebo WorkManager.

Druhý problém — změna signatury metody. V nové verzi API mohla metoda změnit počet nebo typy parametrů. Kompilátor Kotlin/Java hlásí chybu "None of the following functions can be called with the arguments supplied". Řešení: aktualizovat volání metody na novou signaturu nebo přidat kontrolu SDK_INT s voláním staré signatury pro stará zařízení.

// Řešení problémů při zvyšování compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problém: metoda hasSystemFeature změnila signaturu v API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nová signatura: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Stará signatura: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problém: třída odstraněna, používáme AndroidX ekvivalent
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Místo android.app.FragmentManager (odstraněn) používáme
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Třída CompileSdkProblemFixer řeší typické problémy: změněná signatura hasSystemFeature (hypotetická změna v API 36) je ošetřena pomocí SDK_INT kontroly s voláním správné verze metody. Odstraněná třída android.app.FragmentManager byla nahrazena AndroidX ekvivalentem. Pro stará volání, kde není alternativa, se používá @Suppress("DEPRECATION") s komentářem o důvodu zachování.