[Android] targetSdk와 compileSdk의 차이, 그에 따른 영향.

android application을 개발하다 보면,

특히 앱 서비스를 운영하다 보면 버전 대응을 하게 된다.

 

조금만 더듬어 봐도, 분명 Android 15가 나온 지 얼마 안 되었던 것 같은데, 어느새 구글 스토어에서 "너네 앱이 Android 15로 타케팅 하지 않으면 스토어에서 내려버리겠다!"라고 협박받게 되어 부랴부랴 버전 대응을 하게 된 경험이 스쳐 지나간다.

 

미리미리 준비하면 좋겠지만, 기획과 운영을 치다 보면 분명 저 멀리서 홀홀 쳐다보던 신규 버전이 등에 칼을 들이대고 있다.

 

 

이제 곧 Android 16 대응도 슬슬 준비해야 하는 시즌이 되어 가는데,

겸사겸사 Android의 target SDK와 compile SDK에 대해 정리해 보면 좋을 것 같다고 생각했다.

 

---

comileSdk

소스 코드를 컴파일할 때 어떤 Android API 레벨을 기준으로 컴파일할지를 의미한다.

즉, “내가 개발 중에 어떤 Android/Java API를 참조할 수 있는지”의 범위를 결정한다.

 

compileSdk는 “컴파일 시 사용 가능한 Android/Java API를 결정”하는 값인 것이다.

 

app 수준 build.gradle.kts

---

 

compileSdk를 올리면 달라지는 것

• 해당 버전에서 새로 만들어진 API를 코드에서 참조 가능해진다.
• Lint 규칙/Deprecated 경고/빌드 도구 요구사항이 바뀔 수 있다.

 

CompileSdk를 올리게 되면 잘 사용하고 일부 안드로이드 플랫폼 API는 해당 API 레벨에서 사용 불가능(Deprecated 등)할 수 있다.

그렇게 될 경우 개발자는 해당 Sdk에 맞는 API로 수정해 주며, 해당 sdk에 맞게 코드 수정 작업을 하며 대응할 수 있게 되는 것이다.

---

 

때로는 sdk 버전보다 낮은 버전들은 신규 API를 사용하지 못하는 경우가 있는데 이에 따라 다음과 같은 작업이 추가될 수도 있다.

앱 프로젝트는 최신 Sdk를 대응하게 반영하였지만, 실제 사용자 기기의 OS는 그보다 낮을 수 있기 때문에 minSdk까지의 버전은 항상 대응하고 있어야 한다. 

예시: 실제 프로젝트는 35 SDK(Android 15)를 지원하지만 사용자 기기는 Android 10(API 수준 29) 기기를 사용.

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    // API 33+에서만 가능한 동작
} else {
    // 하위 호환 처리
}

 

물론, AndroidX 호환 라이브러리 활용하는 방법도 있다.

 

 

또한, Android Studio는 compileSdk현재 Android Studio 버전, AGP 또는 프로젝트 라이브러리 종속성 요구 사항과 충돌하는 경우 경고를 표시한다.

 

그렇게 Android 개발자는 compileSdk를 올려 해당 Sdk를 사용할 경우 일어날 API 변경 사항 및 빌드 오류를 작업할 수 있게 된다.

 

 

그렇다고 compileSdk를 올린다고 런타임에서 해당 Sdk를 사용하는 것은 아니다.

그렇기 때문에 버전 대응할 때 compileSdk를 먼저 최신 값으로 업데이트하여 대응 작업을 하는 것이 좋다.

 

 

---

 

compileSdk를 올린다고 런타임에서 해당 Sdk를 사용하는 것은 아니다.

그렇다면, 런타임 Sdk는 어떻게 결정이 될까?

 

---

targetSdk

쉽게 말하면, 앱이 ‘이 버전(Android API 레벨)을 목표로 테스트/대응했다’고 시스템에 선언하는 값이다.

 

targetSdk는 다음과 같은 역할을 수행한다.

1. 이 설정은 애플리케이션의 런타임 동작을 지정한다.
2. 어떤 버전의 안드로이드 기기를 대상으로 테스트했는지를 보여준다.

 

즉, 실제로 런타임 될 때 사용하게 되는 Sdk 버전을 지정해 주는 것은 targetSdk인 것이다.

 

app 수준 build.gradle.kts

 

만약 사용 중인 Android 버전이 사용하려고 하는 앱의 targetSdk 버전보다 높은 기기에서 실행하면, Android는 targetSdk에 지정된 하위 버전과 유사하게 작동하는 호환 모드로 앱을 실행한다.

 

 

이게 무슨 말이냐면, 현재 프로젝트에 targetSdk가 34로 설정되어 있지만 실제 실행되는 OS가 API가 35일 경우, 

 

즉, Android 15(API 수준 35)인 기기에서 프로젝트 앱을 실행시킨다면 호환 모드(targetSdk에 명시된 API)로 sdk 35가 아닌 sdk 34로 앱을 실행시키는 것이다.

 

 

다시 말해, 실제 실행하는 앱에서 적용되는 API 수준은 targetSdk가 지정하는 것이다.

 

---

 

build 파일에서 targetSdk값은 compileSdk값과 연관이 없다.

즉, targetSdk 값은 comileSdk 값보다 높거나 같거나 낮을 수 있는 것이다.

The value of targetSdk is not connected to the value of compileSdk. For example, you can have a value of targetSdk that is higher, the same, or lower than compileSdk.

 

 

그렇지만 앞에서 배운 걸 통해 comileSdk와 targetSdk가 일치하지 않을 경우를 우리는 상상할 수 있다.

 

실제로 공식 문서에서 sdk update 대응에 comileSdk를 올린 후 targetSdk를 일치시키는 것을 권장하고 있다.

(즉, comileSdk >= targetSdk를 권장하는 것.)

 

---

위에서의 예시들을 통해 targetSdk가 compileSdk보다 작거나 같은 경우는 어떻게 동작할지 쉽게 예상할 수 있다.

하지만 만약 targetSdk가 클 경우는 어떻게 될까?

---

targetSdk > compileSdk

대부분의 경우 설정 자체가 불가능하거나 빌드가 실패한다.

왜냐하면 targetSdk는 보통 “그 API 레벨을 안다”는 전제인데,
compileSdk가 그 API 수준보다 낮으면 그 API 레벨에 대한 상수/매니페스트 스키마/툴 지원이 부족해서 빌드를 실패하는 것이다

 

 

 

그렇지만 해당 설정 값은 서로 별개로 설정 가능하니 개발자가 build 설정할 때 잘 맞춰주어야 한다~라는 의미로 적어둔 것 같다.

---

추천 업그레이드 순서

1. Android Studio/AGP 업데이트
2. compileSdk 먼저 올림
3. Lint/의존성 문제 해결
4. 버전별 “behavior changes” 문서로 체크리스트 작성
5. targetSdk 올림 + OS별 QA

 

빌드에 포함된 Android SDK

 

---

추가로 학습해 보면 좋을 부분

• 정적 컴파일, 동적 컴파일
• Android build 시스템
• Android 16 버전 대응
• 업데이트 빌드 종속성

 

참고 자료

• Android 빌드 시스템 구성
• 앱 매니페스트 <uses-sdk>
• Android SDK 버전 속성