compileSdkVersion: основи, нови API и настройка в Gradle

Какво е compileSdkVersion в Android?

compileSdkVersion — целочислен параметър в build.gradle, който указва срещу коя версия на Android SDK да се компилира кодът. Когато пишете код, използващ класове от android.* или androidx.*, компилаторът ги проверява с API, налични в посочената версия на compileSdk. Ако метод се появил в API 36 и compileSdk = 35, кодът няма да се компилира. Ако compileSdk = 36 — кодът ще се компилира, но на устройство с API 35 при извикване на този метод без проверка ще възникне грешка.

compileSdkVersion се зарежда от Android SDK Platform, инсталирана чрез SDK Manager в Android Studio. Всяко API Level има своя платформа: android-21, android-29, android-34, android-35, android-36. Платформата съдържа android.jar — набор от класове, методи и константи, с които работи компилаторът Kotlin/Java. Ако платформата не е инсталирана, Gradle ще я изтегли автоматично чрез sdkmanager при първото изграждане.

AGP (Android Gradle Plugin) версия 8.7+ препоръчва посочване на compileSdk като цяло число чрез compileSdk = 36 в Kotlin DSL, без префикс android-. compileSdk може също да бъде посочен чрез compileSdkVersion 36 в Groovy DSL или compileSdkPreview за предварителни версии на SDK (developer previews). compileSdkPreview се използва за тестване на предстоящи API Level преди официалното пускане.

// build.gradle.kts — настройка на compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — последно стабилно API Level (Android 16)
    compileSdk = 36

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

// Алтернативно: compileSdkPreview за предварителни версии
// compileSdkPreview = "Baklava"

В примера compileSdk = 36 предоставя достъп до всички API на Android 16 (Baklava). Android SDK Platform 36 трябва да бъде инсталирана в SDK Manager. compileSdkPreview с име "Baklava" може да се използва за тестване на нестабилни API преди официалното пускане на платформата. След пускането, preview се заменя със стабилен compileSdk = 36.

compileSdkVersion срещу targetSdkVersion срещу minSdkVersion

Три параметъра на API Level в build.gradle — compileSdkVersion, targetSdkVersion и minSdkVersion — често се бъркат. Всеки отговаря за различен аспект на съвместимост и техните стойности трябва да бъдат съгласувани по правилото compileSdk >= targetSdk >= minSdk. minSdk — долна граница: устройства под нея няма да видят приложението. targetSdk — точка на тестване: behavioural changes се включват до това ниво. compileSdk — таван: API над това ниво не са достъпни за компилатора.

Ключово практическо правило: compileSdk може да бъде повишен без никакво тестване на устройства. Това е безопасна операция, която просто дава на компилатора нова версия на android.jar. Единственият риск — остарели API, които могат да бъдат премахнати в новата версия на платформата, но това се открива на етапа на компилиране и лесно се отстранява. Повишаването на targetSdk, напротив, изисква пълен QA цикъл.

Защо compileSdk може да бъде по-висок от targetSdk? Представете си, че излезе Android 16 (API 36) с нови API, които искате да използвате в кода, но behavioural changes на API 36 все още не сте тествали. Задавате compileSdk = 36 (новите API достъпни), targetSdk = 35 (behavioural changes на API 36 изключени). Кодът ще се компилира, ще използва нови методи под SDK_INT проверки и behavioural changes на API 36 няма да счупят приложението, защото targetSdk = 35.

Примери за правилни комбинации

compileSdk = 36, targetSdk = 36, minSdk = 26 — пълна съвместимост с най-новите API и behavioural changes, покритие 85% от устройствата. compileSdk = 36, targetSdk = 34, minSdk = 26 — нови API достъпни, behavioural changes само до API 34. compileSdk = 35, targetSdk = 36 — неправилно: compileSdk по-нисък от targetSdk, API 36 недостъпни, въпреки че behavioural changes 36 са активни.

Как да актуализирате compileSdkVersion: стъпка по стъпка ръководство

Актуализирането на compileSdkVersion — една от най-простите и безопасни операции в Android проект. За разлика от targetSdk, не изисква продължително тестване на behavioural changes. Въпреки това, има няколко стъпки, които трябва да се изпълнят, за да се избегнат грешки при компилиране и предупреждения за остарели елементи.

Стъпка 1 — инсталирайте новата платформа чрез SDK Manager в Android Studio: Tools → SDK Manager → SDK Platforms → изберете новото API Level. Ако не инсталирате платформата, Gradle ще се опита да я изтегли автоматично, но това може да забави първото изграждане. Стъпка 2 — променете compileSdk в build.gradle на новата стойност. Стъпка 3 — изпълнете изграждането (Build → Make Project) и поправете грешките при компилиране.

Стъпка 4 — проверете остарелите API. След повишаване на compileSdk, някои методи може да бъдат маркирани с @Deprecated с бележка "removed in API X". Android Studio ги подчертава със зачертаване и показва предупреждение. Заменете остарелите извиквания с нови алтернативи. Ако алтернативата изисква API Level по-високо от minSdk, добавете runtime проверка. Стъпка 5 — проверете dependencies: някои библиотеки може да изискват определена версия на compileSdk. AGP 8.7+ препоръчва compileSdk = 36.

// След повишаване на compileSdk: замяна на остарели 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 {

    // ПРЕДИ: остарял метод (може да бъде премахнат в ново API)
    @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
    }

    // СЛЕД: нова алтернатива (ако е налична)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Ново API от compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Пример за ново API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Класът CompileSdkMigration показва правилния модел за миграция. Старият метод memoryClass може да бъде премахнат в новото API — компилаторът ще даде грешка. Новата алтернатива getMemoryClassSafe е достъпна само на API 36+, затова се извиква под проверка SDK_INT >= BAKLAVA. За стари устройства се използва fallback с @Suppress("DEPRECATION").

Работа с нови API: conditional checks и fallback

Нови API, достъпни благодарение на повишаването на compileSdkVersion, не могат да бъдат извиквани директно, ако minSdkVersion е по-нисък от това API Level. Без runtime проверка, приложението ще се срине с AbstractMethodError, NoSuchMethodError или VerifyError на стари устройства. Основният защитен механизъм — проверка на Build.VERSION.SDK_INT с извикване на новото API само при достатъчно API Level и fallback за стари версии.

AndroidX предоставя обратна съвместимост за много нови API, което позволява използването на модерни методи дори при нисък compileSdk. Например Activity Result API от androidx.activity:activity-ktx:1.9.3 работи на всички версии на Android от API 14 нататък. NotificationCompat от AndroidX позволява използването на модерни известия на стари API. PhotoPicker е достъпен чрез ActivityResultContracts.PickVisualMedia от API 34+.

// Безопасно извикване на ново API с compileSdk 36 и 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+: нов метод за работа с цвят
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Ново API от compileSdk 36 — изисква API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: ръчно форматиране за стари API
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: обратна съвместимост не се изисква — проверка SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Използване в 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")
    }
}

Класът NewApiHelper демонстрира безопасно извикване на новото API Color.toArgbHexString (хипотетично API 36) с fallback форматиране за стари версии. Ключов принцип: compileSdk предоставя достъп до извикване на нови методи в кода, но runtime проверката SDK_INT предпазва от срив на стари устройства. Без проверка SDK_INT, приложението с minSdk 26 и compileSdk 36 ще се срива на Android 8-15.

AGP (Android Gradle Plugin) и compileSdkVersion

Android Gradle Plugin (AGP) — основният инструмент за изграждане на Android приложения. Всяка версия на AGP поддържа определен диапазон от compileSdkVersion. AGP 8.7.x (пуснат през 2026 г.) изисква compileSdk >= 34 и препоръчва compileSdk = 36. AGP 8.5.x поддържа compileSdk 33-35. Ако compileSdk е по-нисък от минималния за AGP, изграждането ще завърши с грешка "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) също е свързан с compileSdkVersion. Ако проектът използва нативен код на C/C++ чрез NDK, compileSdk определя версията на заглавните файлове и библиотеки. NDK r27+ препоръчва compileSdk 36. За библиотеки с .so файлове, compileSdk влияе на минималното API Level за нативен код чрез APP_MIN_SDK_VERSION в Application.mk.

Gradle (7.6+) и Kotlin (2.0+) също влияят на съвместимостта с compileSdk. AGP 8.7+ изисква Gradle 8.9+ и Kotlin 2.0+. При повишаване на compileSdk се препоръчва актуализиране на AGP, Gradle и Kotlin до последните стабилни версии. Проверете съвместимостта в официалната таблица Android Gradle Plugin compatibility.

Типични проблеми при повишаване на compileSdk

Проблемите при повишаване на compileSdkVersion се делят на три категории: compilation errors, deprecated warnings и runtime incompatibilities. Compilation errors — методи премахнати от API и кодът не се компилира. Deprecated warnings — методи маркирани с @Deprecated, кодът се компилира с предупреждения. Runtime incompatibilities — новите API са задължителни за определена функционалност и причиняват грешка при недостатъчно API Level на устройството.

Първият типичен проблем — "Cannot resolve symbol X". Това означава, че клас или метод е премахнат от публичния API в новата версия на SDK. Решение: намерете алтернатива на новата платформа или използвайте AndroidX еквивалент. Например класът AsyncTaskLoader беше остарял в API 28 и премахнат от публичния API в по-нови версии. Алтернатива — Kotlin Coroutines или WorkManager.

Вторият проблем — промяна на сигнатурата на метод. В новата версия на API, методът може да е променил броя или типовете параметри. Компилаторът Kotlin/Java дава грешка "None of the following functions can be called with the arguments supplied". Решение: актуализирайте извикването на метода към новата сигнатура или добавете проверка SDK_INT с извикване на старата сигнатура за стари устройства.

// Решаване на проблеми при повишаване на compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Проблем: методът hasSystemFeature промени сигнатурата си в API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Нова сигнатура: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Стара сигнатура: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Проблем: клас премахнат, използваме AndroidX еквивалент
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Вместо android.app.FragmentManager (премахнат) използваме
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Класът CompileSdkProblemFixer решава типични проблеми: променената сигнатура на hasSystemFeature (хипотетична промяна в API 36) се обработва чрез SDK_INT проверка с извикване на правилната версия на метода. Премахнатият клас android.app.FragmentManager е заменен с AndroidX еквивалент. За стари извиквания, където няма алтернатива, се използва @Suppress("DEPRECATION") с коментар за причината за запазване.