compileSdkVersion: bazele, API-uri noi și configurarea în Gradle

Ce este compileSdkVersion în Android?

compileSdkVersion — un parametru întreg în build.gradle care specifică împotriva cărei versiuni de Android SDK să se compileze codul. Când scrieți cod care utilizează clase din android.* sau androidx.*, compilatorul le verifică cu API-urile disponibile în versiunea specificată de compileSdk. Dacă o metodă a apărut în API 36, iar compileSdk = 35, codul nu se va compila. Dacă compileSdk = 36 — codul se va compila, dar pe un dispozitiv cu API 35 la apelarea acestei metode fără verificare va apărea o eroare.

compileSdkVersion este încărcat din Android SDK Platform, instalată prin SDK Manager în Android Studio. Fiecare API Level are propria platformă: android-21, android-29, android-34, android-35, android-36. Platforma conține android.jar — un set de clase, metode și constante cu care lucrează compilatorul Kotlin/Java. Dacă platforma nu este instalată, Gradle o va descărca automat prin sdkmanager la primul build.

AGP (Android Gradle Plugin) versiunea 8.7+ recomandă specificarea compileSdk ca număr întreg prin compileSdk = 36 în Kotlin DSL, fără prefixul android-. compileSdk poate fi specificat și prin compileSdkVersion 36 în Groovy DSL sau compileSdkPreview pentru versiunile de previzualizare SDK (developer previews). compileSdkPreview este utilizat pentru testarea API Level-urilor viitoare înainte de lansarea oficială.

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

    // compileSdk = 36 — ultimul API Level stabil (Android 16)
    compileSdk = 36

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

// Alternativ: compileSdkPreview pentru versiunile de previzualizare
// compileSdkPreview = "Baklava"

În exemplu, compileSdk = 36 oferă acces la toate API-urile Android 16 (Baklava). Android SDK Platform 36 trebuie instalată în SDK Manager. compileSdkPreview cu numele "Baklava" poate fi utilizat pentru testarea API-urilor instabile înainte de lansarea oficială a platformei. După lansare, preview este înlocuit cu compileSdk = 36 stabil.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Trei parametri API Level în build.gradle — compileSdkVersion, targetSdkVersion și minSdkVersion — sunt adesea confundați. Fiecare răspunde pentru un aspect diferit al compatibilității, iar valorile lor trebuie să fie coordonate conform regulii compileSdk >= targetSdk >= minSdk. minSdk — limita inferioară: dispozitivele sub acest nivel nu vor vedea aplicația. targetSdk — punctul de testare: behavioural changes se activează până la acest nivel. compileSdk — plafonul: API-urile peste acest nivel sunt indisponibile pentru compilator.

Regula practică cheie: compileSdk poate fi crescut fără nicio testare pe dispozitive. Aceasta este o operațiune sigură care doar oferă compilatorului o nouă versiune de android.jar. Singurul risc — API-urile deprecated care pot fi eliminate în noua versiune a platformei, dar acest lucru se detectează în etapa de compilare și se repară ușor. Creșterea targetSdk, dimpotrivă, necesită un ciclu complet de QA.

De ce compileSdk poate fi mai mare decât targetSdk? Imaginați-vă că a apărut Android 16 (API 36) cu API-uri noi pe care doriți să le utilizați în cod, dar behavioural changes ale API 36 nu le-ați testat încă. Setati compileSdk = 36 (API-uri noi disponibile), targetSdk = 35 (behavioural changes API 36 dezactivate). Codul se va compila, va folosi metode noi sub verificări SDK_INT, iar behavioural changes ale API 36 nu vor strica aplicația deoarece targetSdk = 35.

Exemple de combinații corecte

compileSdk = 36, targetSdk = 36, minSdk = 26 — compatibilitate completă cu cele mai noi API-uri și behavioural changes, acoperire 85% dispozitive. compileSdk = 36, targetSdk = 34, minSdk = 26 — API-uri noi disponibile, behavioural changes doar până la API 34. compileSdk = 35, targetSdk = 36 — incorect: compileSdk mai mic decât targetSdk, API-urile 36 indisponibile, deși behavioural changes 36 sunt active.

Cum să actualizați compileSdkVersion: ghid pas cu pas

Actualizarea compileSdkVersion — una dintre cele mai simple și sigure operațiuni într-un proiect Android. Spre deosebire de targetSdk, nu necesită testarea îndelungată a behavioural changes. Cu toate acestea, există câțiva pași care trebuie urmați pentru a evita erorile de compilare și avertismentele de deprecation.

Pasul 1 — instalați noua platformă prin SDK Manager în Android Studio: Tools → SDK Manager → SDK Platforms → selectați noul API Level. Dacă nu instalați platforma, Gradle va încerca să o descarce automat, dar acest lucru poate încetini primul build. Pasul 2 — modificați compileSdk în build.gradle la noua valoare. Pasul 3 — efectuați build-ul (Build → Make Project) și reparați erorile de compilare.

Pasul 4 — verificați API-urile deprecated. După creșterea compileSdk, unele metode pot fi marcate cu @Deprecated cu mențiunea "removed in API X". Android Studio le evidențiază prin tăiere și afișează un avertisment. Înlocuiți apelurile deprecated cu alternative noi. Dacă alternativa necesită un API Level mai mare decât minSdk, adăugați o verificare la runtime. Pasul 5 — verificați dependencies: unele biblioteci pot necesita o anumită versiune de compileSdk. AGP 8.7+ recomandă compileSdk = 36.

// După creșterea compileSdk: înlocuirea API-urilor deprecated
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 {

    // ÎNAINTE: metodă deprecated (poate fi eliminată în API-ul nou)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Poate fi deprecated în API 36
    }

    // DUPĂ: alternativă nouă (dacă este disponibilă)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // API nou din compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Exemplu API nou
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Clasa CompileSdkMigration arată modelul corect de migrare. Metoda veche memoryClass poate fi eliminată în API-ul nou — compilatorul va da eroare. Noua alternativă getMemoryClassSafe este disponibilă doar pe API 36+, deci este apelată sub verificarea SDK_INT >= BAKLAVA. Pentru dispozitivele vechi se utilizează fallback cu @Suppress("DEPRECATION").

Lucrul cu API-uri noi: verificări condiționale și fallback

API-urile noi, disponibile datorită creșterii compileSdkVersion, nu pot fi apelate direct dacă minSdkVersion este mai mic decât acest API Level. Fără o verificare la runtime, aplicația va crapa cu AbstractMethodError, NoSuchMethodError sau VerifyError pe dispozitivele vechi. Mecanismul principal de protecție — verificarea Build.VERSION.SDK_INT cu apelarea API-ului nou doar la un API Level suficient și fallback pentru versiunile vechi.

AndroidX oferă backport-uri pentru multe API-uri noi, permițând utilizarea metodelor moderne chiar și la un compileSdk scăzut. De exemplu, Activity Result API din androidx.activity:activity-ktx:1.9.3 funcționează pe toate versiunile Android începând cu API 14. NotificationCompat din AndroidX permite utilizarea notificărilor moderne pe API-uri vechi. PhotoPicker este disponibil prin ActivityResultContracts.PickVisualMedia începând cu API 34+.

// Apelarea sigură a unui API nou cu 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+: metodă nouă de lucru cu culoarea
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // API nou din compileSdk 36 — necesită API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: formatare manuală pentru API-uri vechi
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport nu este necesar — verificare SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Utilizare în 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")
    }
}

Clasa NewApiHelper demonstrează apelarea sigură a noului API Color.toArgbHexString (API 36 ipotetic) cu formatare fallback pentru versiunile vechi. Principiul cheie: compileSdk oferă acces la apelarea metodelor noi în cod, dar verificarea runtime SDK_INT protejează de crash pe dispozitivele vechi. Fără verificarea SDK_INT, aplicația cu minSdk 26 și compileSdk 36 va crapa pe Android 8-15.

AGP (Android Gradle Plugin) și compileSdkVersion

Android Gradle Plugin (AGP) — instrumentul principal de build al aplicațiilor Android. Fiecare versiune AGP suportă un anumit interval de compileSdkVersion. AGP 8.7.x (lansat în 2026) necesită compileSdk >= 34 și recomandă compileSdk = 36. AGP 8.5.x suportă compileSdk 33-35. Dacă compileSdk este mai mic decât minimul pentru AGP, build-ul se va încheia cu eroarea "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) este de asemenea legat de compileSdkVersion. Dacă proiectul utilizează cod nativ în C/C++ prin NDK, compileSdk determină versiunea fișierelor header și bibliotecilor. NDK r27+ recomandă compileSdk 36. Pentru bibliotecile cu fișiere .so, compileSdk influențează API Level minim pentru codul nativ prin APP_MIN_SDK_VERSION în Application.mk.

Gradle (7.6+) și Kotlin (2.0+) influențează de asemenea compatibilitatea cu compileSdk. AGP 8.7+ necesită Gradle 8.9+ și Kotlin 2.0+. La creșterea compileSdk, se recomandă actualizarea AGP, Gradle și Kotlin la cele mai recente versiuni stabile. Verificați compatibilitatea în tabela oficială Android Gradle Plugin compatibility.

Probleme tipice la creșterea compileSdk

Problemele la creșterea compileSdkVersion se împart în trei categorii: compilation errors, deprecated warnings și runtime incompatibilities. Compilation errors — metode eliminate din API și codul nu se compilează. Deprecated warnings — metode marcate cu @Deprecated, codul se compilează cu avertismente. Runtime incompatibilities — API-urile noi sunt obligatorii pentru anumite funcționalități și provoacă erori la un API Level insuficient pe dispozitiv.

Prima problemă tipică — "Cannot resolve symbol X". Aceasta înseamnă că o clasă sau o metodă a fost eliminată din API-ul public în noua versiune SDK. Soluție: găsiți o alternativă în noua platformă sau utilizați echivalentul AndroidX. De exemplu, clasa AsyncTaskLoader a fost deprecated în API 28 și eliminată din API-ul public în versiunile mai noi. Alternativă — Kotlin Coroutines sau WorkManager.

A doua problemă — modificarea semnăturii metodei. În noua versiune API, metoda poate fi schimbat numărul sau tipurile parametrilor. Compilatorul Kotlin/Java dă eroarea "None of the following functions can be called with the arguments supplied". Soluție: actualizați apelul metodei la noua semnătură sau adăugați verificarea SDK_INT cu apelarea semnăturii vechi pentru dispozitivele vechi.

// Rezolvarea problemelor la creșterea 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 a schimbat semnătura în API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Semnătură nouă: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Semnătură veche: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problemă: clasă eliminată, folosim echivalentul AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // În loc de android.app.FragmentManager (eliminat) folosim
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Clasa CompileSdkProblemFixer rezolvă problemele tipice: semnătura modificată a hasSystemFeature (schimbare ipotetică în API 36) este gestionată prin verificarea SDK_INT cu apelarea versiunii corecte a metodei. Clasa eliminată android.app.FragmentManager a fost înlocuită cu echivalentul AndroidX. Pentru apelurile vechi unde nu există alternativă, se utilizează @Suppress("DEPRECATION") cu un comentariu despre motivul păstrării.