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 используется для тестирования upcoming 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 vs targetSdkVersion vs minSdkVersion

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

Ключевое практическое правило: compileSdk можно повысить без какого-либо тестирования на устройствах. Это безопасная операция, которая лишь даёт компилятору новую версию android.jar. Единственный риск — deprecated 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. Однако есть несколько шагов, которые нужно выполнить, чтобы избежать ошибок компиляции и deprecated-предупреждений.

Шаг 1 — установите новую платформу через SDK Manager в Android Studio: Tools → SDK Manager → SDK Platforms → выберите новый API Level. Если не установить платформу, Gradle попытается загрузить её автоматически, но это может замедлить первую сборку. Шаг 2 — измените compileSdk в build.gradle на новое значение. Шаг 3 — выполните сборку (Build → Make Project) и исправьте ошибки компиляции.

Шаг 4 — проверьте deprecated API. После повышения compileSdk некоторые методы могут оказаться помеченными @Deprecated с пометкой "removed in API X". Android Studio подсвечивает зачёркиванием и выдаёт warning. Замените deprecated-вызовы на новые альтернативы. Если альтернатива требует API Level выше minSdk, добавьте runtime-проверку. Шаг 5 — проверьте dependencies: некоторые библиотеки могут требовать определённую версию compileSdk. AGP 8.7+ рекомендует compileSdk = 36.

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

    // ДО: deprecated метод (может быть удалён в новом API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Может быть deprecated в 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 был deprecated в 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") с комментарием о причине сохранения.