compileSdkVersion: 기본, 새로운 API 및 Gradle 설정

Android에서 compileSdkVersion이란?

compileSdkVersion은 build.gradle의 정수 매개변수로, 코드를 컴파일할 Android SDK 버전을 지정합니다. android.* 또는 androidx.*의 클래스를 사용하여 코드를 작성하면 컴파일러는 지정된 compileSdk 버전에서 사용 가능한 API와 대조합니다. 메서드가 API 36에서 도입되었고 compileSdk = 35인 경우 코드가 컴파일되지 않습니다. compileSdk = 36인 경우 코드는 컴파일되지만 확인 없이 API 35 기기에서 해당 메서드를 호출하면 충돌이 발생합니다.

compileSdkVersion은 Android Studio의 SDK Manager를 통해 설치된 Android SDK Platform에서 로드됩니다. 각 API 레벨에는 자체 플랫폼이 있습니다: android-21, android-29, android-34, android-35, android-36. 플랫폼에는 Kotlin/Java 컴파일러가 사용하는 클래스, 메서드 및 상수 집합인 android.jar가 포함됩니다. 플랫폼이 설치되지 않은 경우 Gradle은 첫 번째 빌드 시 sdkmanager를 통해 자동으로 다운로드합니다.

AGP(Android Gradle Plugin) 버전 8.7+는 Kotlin DSL에서 android- 접두사 없이 compileSdk = 36으로 정수로 compileSdk를 지정할 것을 권장합니다. compileSdk는 Groovy DSL에서 compileSdkVersion 36을 통해 또는 프리릴리스 SDK 버전(개발자 프리뷰)용 compileSdkPreview를 통해 설정할 수도 있습니다. compileSdkPreview는 공식 출시 전에 예정된 API 레벨을 테스트하는 데 사용됩니다.

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

    // compileSdk = 36 — 최신 안정 API 레벨(Android 16)
    compileSdk = 36

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

// 대안: 프리뷰 버전용 compileSdkPreview
// compileSdkPreview = "Baklava"

예제에서 compileSdk = 36은 모든 Android 16(Baklava) API에 대한 액세스를 제공합니다. Android SDK Platform 36은 SDK Manager에 설치되어야 합니다. "Baklava"라는 이름의 compileSdkPreview는 공식 플랫폼 출시 전에 불안정한 API를 테스트하는 데 사용할 수 있습니다. 출시 후 프리뷰는 안정적인 compileSdk = 36으로 대체됩니다.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

build.gradle의 세 가지 API 레벨 매개변수 — compileSdkVersion, targetSdkVersion 및 minSdkVersion — 은 종종 혼동됩니다. 각각은 호환성의 다른 측면을 담당하며 값은 compileSdk >= targetSdk >= minSdk 규칙을 따라야 합니다. minSdk는 하한선입니다: 이보다 낮은 기기는 앱을 볼 수 없습니다. targetSdk는 테스트 지점입니다: 이 레벨까지 동작 변경이 활성화됩니다. compileSdk는 상한선입니다: 이 레벨 위의 API는 컴파일러가 사용할 수 없습니다.

중요한 실용 규칙: compileSdk는 기기 테스트 없이도 높일 수 있습니다. 이는 컴파일러에 새 버전의 android.jar를 제공하는 안전한 작업입니다. 유일한 위험은 새 플랫폼 버전에서 제거될 수 있는 더 이상 사용되지 않는 API이지만 이는 컴파일 시 감지되어 쉽게 수정됩니다. 반면 targetSdk를 높이려면 전체 QA 주기가 필요합니다.

compileSdk가 targetSdk보다 높을 수 있는 이유는 무엇인가요? Android 16(API 36)이 코드에서 사용하려는 새로운 API와 함께 출시되었지만 아직 API 36의 동작 변경을 테스트하지 않았다고 가정해 보세요. compileSdk = 36(새 API 사용 가능), targetSdk = 35(API 36 동작 변경 비활성화)로 설정합니다. 코드는 컴파일되고 SDK_INT 확인 아래에서 새 메서드를 사용하며 targetSdk = 35이므로 API 36의 동작 변경이 앱을 중단시키지 않습니다.

올바른 조합의 예

compileSdk = 36, targetSdk = 36, minSdk = 26 — 최신 API 및 동작 변경과의 완전한 호환성, 기기의 85% 커버. compileSdk = 36, targetSdk = 34, minSdk = 26 — 새 API 사용 가능, 동작 변경은 API 34까지만. compileSdk = 35, targetSdk = 36 — 올바르지 않음: compileSdk가 targetSdk보다 낮고 API 36을 사용할 수 없지만 36의 동작 변경은 활성 상태.

compileSdkVersion 업데이트 방법: 단계별 가이드

compileSdkVersion 업데이트는 Android 프로젝트에서 가장 간단하고 안전한 작업 중 하나입니다. targetSdk와 달리 동작 변경에 대한 광범위한 테스트가 필요하지 않습니다. 그러나 컴파일 오류 및 사용 중단 경고를 피하기 위해 따라야 할 몇 가지 단계가 있습니다.

1단계 — Android Studio의 SDK Manager를 통해 새 플랫폼 설치: Tools → SDK Manager → SDK Platforms → 새 API 레벨 선택. 플랫폼을 설치하지 않으면 Gradle이 자동으로 다운로드하려고 시도하지만 첫 번째 빌드가 느려질 수 있습니다. 2단계 — build.gradle에서 compileSdk를 새 값으로 변경. 3단계 — 빌드(Build → Make Project)하고 컴파일 오류 수정.

4단계 — 더 이상 사용되지 않는 API 확인. compileSdk를 높인 후 일부 메서드는 "removed in API X" 메모와 함께 @Deprecated로 표시될 수 있습니다. Android Studio는 취소선으로 강조 표시하고 경고를 표시합니다. 더 이상 사용되지 않는 호출을 새 대안으로 교체하십시오. 대안에 minSdk보다 높은 API 레벨이 필요한 경우 런타임 확인을 추가하십시오. 5단계 — 종속성 확인: 일부 라이브러리는 특정 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) {
            // compileSdk 36의 새 API
            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 확인 하에 호출됩니다. 이전 기기의 경우 @Suppress("DEPRECATION")와 함께 폴백이 사용됩니다.

새로운 API 작업: 조건부 확인 및 폴백

새로운 API는 compileSdkVersion 업그레이드로 사용할 수 있게 되지만 minSdkVersion이 해당 API 레벨보다 낮으면 직접 호출할 수 없습니다. 런타임 확인 없이 이전 기기에서 AbstractMethodError, NoSuchMethodError 또는 VerifyError와 함께 앱이 충돌합니다. 주요 보호 메커니즘은 Build.VERSION.SDK_INT를 확인하고 API 레벨이 충분할 때만 새 API를 호출하며 이전 버전에 대한 폴백을 제공하는 것입니다.

AndroidX는 많은 새로운 API에 대한 백포트를 제공하여 낮은 compileSdk에서도 최신 메서드를 사용할 수 있게 합니다. 예를 들어, androidx.activity:activity-ktx:1.9.3의 Activity Result API는 API 14부터 모든 Android 버전에서 작동합니다. AndroidX의 NotificationCompat은 이전 API에서 최신 알림을 가능하게 합니다. PhotoPicker는 API 34+부터 ActivityResultContracts.PickVisualMedia를 통해 사용할 수 있습니다.

// compileSdk 36 및 minSdk 26으로 새 API 안전 호출
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) {
            // compileSdk 36의 새 API — API 36+ 필요
            return Color.toArgbHexString(colorInt)
        }
        // 폴백: 이전 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)의 안전한 호출을 보여줍니다. 핵심 원칙: compileSdk는 코드에서 새 메서드를 호출하는 액세스를 제공하지만 런타임 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에 연결됩니다. 프로젝트가 NDK를 통해 C/C++ 네이티브 코드를 사용하는 경우 compileSdk는 헤더 파일 및 라이브러리의 버전을 결정합니다. NDK r27+는 compileSdk 36을 권장합니다. .so 파일이 있는 라이브러리의 경우 compileSdk는 Application.mk의 APP_MIN_SDK_VERSION을 통해 네이티브 코드의 최소 API 레벨에 영향을 줍니다.

Gradle(7.6+) 및 Kotlin(2.0+)도 compileSdk 호환성에 영향을 줍니다. AGP 8.7+에는 Gradle 8.9+ 및 Kotlin 2.0+가 필요합니다. compileSdk를 업그레이드할 때 AGP, Gradle 및 Kotlin을 최신 안정 버전으로 업데이트하는 것이 좋습니다. 공식 Android Gradle Plugin 호환성 표에서 호환성을 확인하십시오.

compileSdk 업그레이드 시 일반적인 문제

compileSdkVersion 업그레이드 시 문제는 세 가지 범주로 나뉩니다: 컴파일 오류, 사용 중단 경고 및 런타임 비호환성. 컴파일 오류 — 메서드가 API에서 제거되고 코드가 컴파일되지 않음. 사용 중단 경고 — 메서드가 @Deprecated로 표시되고 코드가 경고와 함께 컴파일됨. 런타임 비호환성 — 새 API가 특정 기능에 필요하며 기기의 API 레벨이 충분하지 않으면 오류가 발생함.

첫 번째 일반적인 문제 — "Cannot resolve symbol X". 이는 클래스나 메서드가 새 SDK 버전의 공개 API에서 제거되었음을 의미합니다. 해결책: 새 플랫폼에서 대안을 찾거나 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")이 유지 이유를 설명하는 주석과 함께 사용됩니다.