compileSdkVersion: Grundlagen, neue APIs und Konfiguration in Gradle

Was ist compileSdkVersion in Android?

compileSdkVersion ist ein ganzzahliger Parameter in build.gradle, der angibt, gegen welche Version des Android SDK der Code kompiliert werden soll. Wenn Sie Code schreiben, der Klassen aus android.* oder androidx.* verwendet, prüft der Compiler diese gegen die in der angegebenen compileSdk-Version verfügbaren APIs. Wenn eine Methode in API 36 eingeführt wurde und compileSdk = 35 ist, wird der Code nicht kompiliert. Wenn compileSdk = 36 ist, wird der Code kompiliert, aber der Aufruf dieser Methode auf einem Gerät mit API 35 ohne Prüfung führt zu einem Absturz.

compileSdkVersion wird von der Android SDK Platform geladen, die über den SDK Manager in Android Studio installiert wird. Jede API-Ebene hat ihre eigene Plattform: android-21, android-29, android-34, android-35, android-36. Die Plattform enthält android.jar — eine Sammlung von Klassen, Methoden und Konstanten, die der Kotlin/Java-Compiler verwendet. Wenn die Plattform nicht installiert ist, lädt Gradle sie beim ersten Build automatisch über sdkmanager herunter.

AGP (Android Gradle Plugin) Version 8.7+ empfiehlt, compileSdk als Ganzzahl über compileSdk = 36 im Kotlin-DSL ohne das android-Präfix anzugeben. compileSdk kann auch über compileSdkVersion 36 im Groovy-DSL oder compileSdkPreview für Vorabversionen des SDK (Developer Previews) festgelegt werden. compileSdkPreview wird zum Testen bevorstehender API-Ebenen vor der offiziellen Veröffentlichung verwendet.

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

    // compileSdk = 36 — neueste stabile API-Ebene (Android 16)
    compileSdk = 36

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

// Alternativ: compileSdkPreview für Vorschauversionen
// compileSdkPreview = "Baklava"

Im Beispiel bietet compileSdk = 36 Zugriff auf alle Android 16 (Baklava)-APIs. Die Android SDK Platform 36 muss im SDK Manager installiert sein. compileSdkPreview mit dem Namen "Baklava" kann zum Testen instabiler APIs vor der offiziellen Plattformveröffentlichung verwendet werden. Nach der Veröffentlichung wird die Vorschau durch das stabile compileSdk = 36 ersetzt.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Drei API-Ebenen-Parameter in build.gradle — compileSdkVersion, targetSdkVersion und minSdkVersion — werden oft verwechselt. Jeder ist für einen anderen Aspekt der Kompatibilität verantwortlich, und ihre Werte müssen der Regel compileSdk >= targetSdk >= minSdk folgen. minSdk ist die Untergrenze: Geräte darunter sehen die App nicht. targetSdk ist der Testpunkt: Verhaltensänderungen werden bis zu dieser Ebene aktiviert. compileSdk ist die Obergrenze: APIs oberhalb dieser Ebene sind für den Compiler nicht verfügbar.

Wichtige praktische Regel: compileSdk kann ohne Gerätetests erhöht werden. Dies ist eine sichere Operation, die dem Compiler lediglich eine neue Version von android.jar zur Verfügung stellt. Das einzige Risiko sind veraltete APIs, die in der neuen Plattformversion entfernt werden könnten, aber dies wird zur Kompilierzeit erkannt und leicht behoben. Das Erhöhen von targetSdk erfordert dagegen einen vollständigen QA-Zyklus.

Warum kann compileSdk höher als targetSdk sein? Stellen Sie sich vor, Android 16 (API 36) wurde mit neuen APIs veröffentlicht, die Sie im Code verwenden möchten, aber Sie haben die Verhaltensänderungen von API 36 noch nicht getestet. Sie setzen compileSdk = 36 (neue APIs verfügbar), targetSdk = 35 (Verhaltensänderungen von API 36 deaktiviert). Der Code wird kompiliert, verwendet neue Methoden unter SDK_INT-Prüfungen, und die Verhaltensänderungen von API 36 werden die App nicht beeinträchtigen, da targetSdk = 35 ist.

Beispiele für korrekte Kombinationen

compileSdk = 36, targetSdk = 36, minSdk = 26 — vollständige Kompatibilität mit den neuesten APIs und Verhaltensänderungen, Abdeckung von 85% der Geräte. compileSdk = 36, targetSdk = 34, minSdk = 26 — neue APIs verfügbar, Verhaltensänderungen nur bis API 34. compileSdk = 35, targetSdk = 36 — falsch: compileSdk ist niedriger als targetSdk, API 36 nicht verfügbar, während die Verhaltensänderungen von 36 aktiv sind.

So aktualisieren Sie compileSdkVersion: Schritt-für-Schritt-Anleitung

compileSdkVersion aktualisieren ist eine der einfachsten und sichersten Operationen in einem Android-Projekt. Im Gegensatz zu targetSdk erfordert es keine umfangreichen Tests von Verhaltensänderungen. Es gibt jedoch einige Schritte zu befolgen, um Kompilierungsfehler und Veraltungswarnungen zu vermeiden.

Schritt 1 — installieren Sie die neue Plattform über den SDK Manager in Android Studio: Tools → SDK Manager → SDK Platforms → wählen Sie die neue API-Ebene. Wenn Sie die Plattform nicht installieren, versucht Gradle, sie automatisch herunterzuladen, was jedoch den ersten Build verlangsamen kann. Schritt 2 — ändern Sie compileSdk in build.gradle auf den neuen Wert. Schritt 3 — führen Sie einen Build durch (Build → Make Project) und beheben Sie etwaige Kompilierungsfehler.

Schritt 4 — prüfen Sie auf veraltete APIs. Nach dem Upgrade von compileSdk können einige Methoden als @Deprecated mit dem Hinweis "removed in API X" markiert sein. Android Studio hebt sie mit Durchstreichung hervor und zeigt eine Warnung an. Ersetzen Sie veraltete Aufrufe durch neue Alternativen. Wenn die Alternative eine höhere API-Ebene als minSdk erfordert, fügen Sie eine Laufzeitprüfung hinzu. Schritt 5 — überprüfen Sie die Abhängigkeiten: Einige Bibliotheken erfordern möglicherweise eine bestimmte compileSdk-Version. AGP 8.7+ empfiehlt compileSdk = 36.

// Nach compileSdk-Upgrade: Ersetzen veralteter APIs
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 {

    // VORHER: veraltete Methode (kann in der neuen API entfernt werden)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Kann in API 36 veraltet sein
    }

    // NACHHER: neue Alternative (falls verfügbar)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Neue API aus compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Beispiel einer neuen API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Die Klasse CompileSdkMigration zeigt das korrekte Migrationsmuster. Die alte Methode memoryClass kann in der neuen API entfernt werden — der Compiler gibt einen Fehler aus. Die neue Alternative getMemoryClassSafe ist nur auf API 36+ verfügbar, daher wird sie unter einer SDK_INT >= BAKLAVA-Prüfung aufgerufen. Für ältere Geräte wird ein Fallback mit @Suppress("DEPRECATION") verwendet.

Arbeiten mit neuen APIs: Bedingte Prüfungen und Fallback

Neue APIs, die durch das Upgrade von compileSdkVersion verfügbar werden, können nicht direkt aufgerufen werden, wenn minSdkVersion niedriger als diese API-Ebene ist. Ohne eine Laufzeitprüfung stürzt die App auf älteren Geräten mit AbstractMethodError, NoSuchMethodError oder VerifyError ab. Der primäre Schutzmechanismus ist die Prüfung von Build.VERSION.SDK_INT, wobei die neue API nur bei ausreichender API-Ebene aufgerufen wird, und ein Fallback für ältere Versionen bereitgestellt wird.

AndroidX bietet Backports für viele neue APIs, sodass moderne Methoden auch mit einem niedrigen compileSdk verwendet werden können. Beispielsweise funktioniert die Activity Result API von androidx.activity:activity-ktx:1.9.3 auf allen Android-Versionen ab API 14. NotificationCompat von AndroidX ermöglicht moderne Benachrichtigungen auf alten APIs. PhotoPicker ist über ActivityResultContracts.PickVisualMedia ab API 34+ verfügbar.

// Sicherer Aufruf neuer API mit compileSdk 36 und 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+: neue Methode zum Arbeiten mit Farbe
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Neue API aus compileSdk 36 — erfordert API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: manuelle Formatierung für alte APIs
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: kein Backport nötig — SDK_INT-Prüfung
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Verwendung in 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")
    }
}

Die Klasse NewApiHelper demonstriert den sicheren Aufruf der neuen API Color.toArgbHexString (hypothetische API 36) mit Fallback-Formatierung für ältere Versionen. Das Schlüsselprinzip: compileSdk gewährt Zugriff zum Aufrufen neuer Methoden im Code, aber eine Laufzeit-SDK_INT-Prüfung schützt vor Abstürzen auf älteren Geräten. Ohne SDK_INT-Prüfung stürzt eine App mit minSdk 26 und compileSdk 36 auf Android 8-15 ab.

AGP (Android Gradle Plugin) und compileSdkVersion

Android Gradle Plugin (AGP) ist das primäre Build-Tool für Android-Anwendungen. Jede AGP-Version unterstützt einen bestimmten Bereich von compileSdkVersion. AGP 8.7.x (veröffentlicht 2026) erfordert compileSdk >= 34 und empfiehlt compileSdk = 36. AGP 8.5.x unterstützt compileSdk 33-35. Wenn compileSdk unter dem für AGP erforderlichen Minimum liegt, schlägt der Build mit dem Fehler fehl: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) ist ebenfalls an compileSdkVersion gebunden. Wenn Ihr Projekt nativen C/C++-Code über NDK verwendet, bestimmt compileSdk die Version der Header-Dateien und Bibliotheken. NDK r27+ empfiehlt compileSdk 36. Für Bibliotheken mit .so-Dateien beeinflusst compileSdk die minimale API-Ebene für nativen Code über APP_MIN_SDK_VERSION in Application.mk.

Gradle (7.6+) und Kotlin (2.0+) beeinflussen ebenfalls die compileSdk-Kompatibilität. AGP 8.7+ erfordert Gradle 8.9+ und Kotlin 2.0+. Beim Upgrade von compileSdk wird empfohlen, AGP, Gradle und Kotlin auf die neuesten stabilen Versionen zu aktualisieren. Überprüfen Sie die Kompatibilität in der offiziellen Android Gradle Plugin-Kompatibilitätstabelle.

Häufige Probleme beim Upgrade von compileSdk

Probleme beim Upgrade von compileSdkVersion fallen in drei Kategorien: Kompilierungsfehler, Veraltungswarnungen und Laufzeitinkompatibilitäten. Kompilierungsfehler — Methoden werden aus der API entfernt und der Code wird nicht kompiliert. Veraltungswarnungen — Methoden sind als @Deprecated markiert, der Code wird mit Warnungen kompiliert. Laufzeitinkompatibilitäten — neue APIs sind für bestimmte Funktionen erforderlich und verursachen Fehler, wenn die API-Ebene auf dem Gerät nicht ausreicht.

Das erste häufige Problem — "Cannot resolve symbol X". Dies bedeutet, dass eine Klasse oder Methode aus der öffentlichen API in der neuen SDK-Version entfernt wurde. Lösung: Finden Sie eine Alternative in der neuen Plattform oder verwenden Sie ein AndroidX-Äquivalent. Beispielsweise wurde die Klasse AsyncTaskLoader in API 28 als veraltet markiert und in neueren Versionen aus der öffentlichen API entfernt. Alternativen sind Kotlin Coroutines oder WorkManager.

Das zweite Problem — Methodensignaturänderung. In der neuen API-Version kann eine Methode die Anzahl oder Art ihrer Parameter geändert haben. Der Kotlin/Java-Compiler gibt einen Fehler aus: "None of the following functions can be called with the arguments supplied". Lösung: Aktualisieren Sie den Methodenaufruf an die neue Signatur oder fügen Sie eine SDK_INT-Prüfung mit dem Aufruf der alten Signatur für ältere Geräte hinzu.

// Problemlösung beim Upgrade von compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problem: Methode hasSystemFeature hat Signatur in API 36 geändert
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Neue Signatur: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Alte Signatur: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problem: Klasse entfernt, AndroidX-Äquivalent verwenden
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Statt android.app.FragmentManager (entfernt) verwenden
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Die Klasse CompileSdkProblemFixer löst häufige Probleme: Die geänderte Signatur von hasSystemFeature (hypothetische Änderung in API 36) wird über eine SDK_INT-Prüfung behandelt, die die korrekte Version der Methode aufruft. Die entfernte Klasse android.app.FragmentManager wird durch das AndroidX-Äquivalent ersetzt. Für alte Aufrufe, bei denen keine Alternative existiert, wird @Suppress("DEPRECATION") mit einem Kommentar verwendet, der den Grund für die Beibehaltung erklärt.