App Desugaring

App desugaring(= Java 8+ AP#I / core library desugaring)이 “무엇을” 해결하는 방식인가

Android 앱은 JVM이 아니라 ART(Android Runtime) 위에서 실행됩니다. 그래서 빌드 결과물은 “JVM 바이트코드(.class)”가 아니라, ART가 실행하는 바이트코드 포맷(DEX) 로 패키징되어야 합니다.
이 과정은 보통 D8/R8이 .class → .dex로 컴파일(dexing) 하면서 수행합니다.

문제는, Android가 OS 버전(API 레벨)에 따라 제공하는 Java 표준 라이브러리 API 범위가 다르다는 점입니다. 예를 들어 java.util.stream.* 같은 API는 낮은 OS에 없기 때문에, 해당 API를 사용하는 코드(내 코드든 3rd party든)가 실행되면 대표적으로 NoClassDefFoundError/ClassNotFoundException 류의 런타임 오류가 발생할 수 있습니다.

App desugaring(공식 명칭: Java 8+ API desugaring / core library desugaring) 은 이 문제를 해결하기 위해

• (1) 앱에 “부족한 Java 표준 API 구현”을 같이 번들링(실제로는 desugared library가 포함된 DEX/클래스들이 앱에 들어옴)하고
• (2) 컴파일 단계에서 호출 지점을 리라이트(rewrite) 해서
• (3) 런타임에 “플랫폼에 없는 API”를 앱이 포함한 구현으로 대체(backport) 하여 사용하게 만드는 기능입니다.

요약: “OS에 없는 Java 표준 API를 앱이 함께 들고 가서(backport) 실행되게 한다.”

---

desugar를 이해하기 위한 Q&A (꼬리 질문 포함)

Q1. 왜 .class를 그대로 쓰지 않고 .dex로 만드나? (AGP가 굳이 변환하는 이유)

A. Android 기기에서 앱은 JVM이 아니라 ART가 실행합니다. ART는 JVM .class를 직접 실행하는 게 아니라, 앱이 패키징한 DEX 바이트코드를 실행합니다.
그래서 빌드 파이프라인은 필수적으로 .class → .dex 컴파일을 수행합니다. 이 역할을 D8(또는 R8)이 합니다.

개발자 관점 요약: .class → .dex는 “XML→JSON 같은 단순 포맷 치환”에 가깝기보단, 실행 머신이 다른 환경(ART)을 위한 컴파일에 가깝습니다.

---

Q2. 그러면 “desugar”는 .class → .dex 변환 자체를 의미하나?

A. 정확히는 아닙니다.

• dexing: .class → .dex로 “ART 실행 포맷”을 만드는 컴파일 작업(D8/R8의 역할)
• desugaring: dexing 과정에서(또는 그 직전/직후에) 호환성 확보를 위해 바이트코드를 추가 변환/리라이트하는 작업

즉, desugar는 “dex로 바꾸는 것”이 아니라 dex로 바꾸는 과정에 끼어드는 ‘추가 변환’이라고 보는 게 정확합니다.

---

Q3. ‘낮은 런타임에서도 동작한다’는 게 무슨 뜻?

A. “낮은 런타임”은 보통 **낮은 Android API 레벨(= 오래된 OS)**을 뜻합니다. 낮은 OS에서는

1. 언어 기능: (예: 람다, default interface method 등) 특정 바이트코드 패턴이 그대로 유지되면 안전하지 않을 수 있어 D8/R8이 “더 단순한 형태”로 풀어주는 변환이 필요합니다.
   → 이걸 흔히 언어 기능 desugaring이라고 부릅니다.

2. 표준 라이브러리 API: (예: java.util.stream, java.time 일부) OS에 클래스 자체가 없어서 그대로 실행하면 NoClass 에러가 납니다.
   → 이걸 해결하기 위해 “앱이 구현을 포함 + 호출을 그 구현으로 바꿈”이 필요하고, 그게 core library desugaring(App desugaring) 입니다.

한 줄 요약:

• 언어 desugar: “문법/바이트코드 패턴”을 낮은 환경에서도 되게 변환
• API desugar: “없는 표준 API 구현”을 앱에 포함 + 호출 리라이트

---

Q4. core library desugaring은 ‘패키지명을 옛 패키지로 연결(alias)’해주는 건가?

A. “별칭(alias)로 연결”이라기보다는, 플랫폼(java.*)과 충돌을 피하기 위한 네임스페이스/리라이트 전략에 가깝습니다.

• Android 플랫폼의 java.*는 bootclasspath에 있고 앱이 이를 “덮어쓰기”할 수 없습니다.
• 그래서 desugared library 구현은 충돌 회피를 위해 별도 네임스페이스(예: j$.*)로 들어오거나, 규칙에 따라 특정 prefix를 rewrite하는 방식으로 동작합니다.
• 일부 케이스는 최신 OS에서는 플랫폼 클래스가 우선 사용되고(bootclasspath 우선), 낮은 OS에서는 desugared 구현이 사용되기도 합니다. (이건 코드 분기라기보다는 “어떤 클래스를 로딩하느냐”의 성격)

---

Q5. 그럼 DEX 안에는 Android 버전별 분기(if SDK_INT…)가 잔뜩 들어가나?

A. 보통은 아닙니다. 핵심은 “런타임에서 minSdk를 확인해 뭔가를 추가”가 아니라,

• 빌드 시점에 이미 minSdk가 정해져 있고, 그 값에 맞춰 D8/R8이 변환/리라이트/라이브러리 포함을 수행해
• APK에 고정된 결과물로 들어갑니다.

다만 core library desugaring은 “클래스 로딩 우선순위(플랫폼 우선)” 같은 이유로 결과적으로 OS에 따라 다른 구현이 사용되는 것처럼 보일 수는 있습니다(하지만 일반적인 if (SDK_INT >= …) 분기 코드가 증가하는 형태는 흔치 않음).

---

왜(언제) 필요한가

아래 중 하나라도 해당하면 ‘API desugaring’이 필요해질 수 있습니다.

• 내 코드가 Java 8+ API를 직접 사용해야 한다.
  • 예: Stream API(java.util.stream) 등
• 의존 라이브러리(3rd party)가 Java 8+ API를 사용한다.
  • 앱이 직접 안 쓰더라도 의존성 내부 호출 때문에 런타임/검증 문제가 발생할 수 있음
• 특정 SDK가 “core library desugaring을 필수 빌드 요건”으로 요구한다.
  • 이 경우는 “OS 미지원”과 별개로, “SDK 릴리즈 정책/빌드 가정” 때문에 업그레이드가 막힐 수 있음

참고: “Java 8 언어 기능(람다 등)”은 기본 desugar(언어 기능)로 해결되고,
여기서 말하는 ‘App desugaring’은 표준 라이브러리 API(클래스/메서드)까지 확장(backport)하는 기능을 의미합니다.

---

(공식 문서 관점) App desugaring이 실제로 하는 일

Android Gradle Plugin(AGP)에서 API desugaring을 켜면:

1. missing API 구현을 포함한 라이브러리(desugared library)를 앱에 포함합니다.
2. desugaring 과정에서 앱의 호출 지점을 변환(rewrite) 하여, 런타임에 그 구현을 쓰게 합니다.
3. 제공되는 API 범위는 desugar_jdk_libs(및 AGP/버전)에 따라 달라집니다.

---

설정(예시)

아래는 공식 문서의 대표 설정 형태를 그대로 요약한 예시입니다.

Kotlin DSL (build.gradle.kts)

android {
  compileOptions {
    // AGP 4.1+
    isCoreLibraryDesugaringEnabled = true
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}
 
dependencies {
  coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.3")
}

---

눈으로 보는 증거(“정말 뭐가 추가되고, 뭐가 바뀌나?”)

아래는 프로젝트에서 바로 확인 가능한 체크리스트입니다.

1) APK에 “추가된 표준 라이브러리 구현”이 들어왔는지

• Android Studio Analyze APK 또는 jadx로 APK 열기
• 클래스 검색:
  • j$/util/stream/
  • j$/time/
  • j$/util/function/ → 이런 패키지가 보이면 “플랫폼에 없는 API 구현이 앱에 번들링되었다”는 강한 증거입니다.

2) 호출이 rewrite 되었는지(소스는 java.util.stream인데 결과물은?)

• stream()/java.util.stream 사용 지점을 디컴파일해서 확인
• desugaring이 적용된 경우, 내부적으로 j$.util.stream 계열 호출 흔적이 보이는 경우가 많습니다.

3) 언어 desugar 흔적(람다 등)

• 결과물에서 $$ExternalSyntheticLambda / $$Lambda$... 같은 synthetic 클래스 흔적을 확인 → “람다가 원형 그대로”가 아니라, 낮은 환경에서도 안전한 형태로 풀렸다는 단서입니다.

---

실무에서 체크해야 하는 영향(리스크/운영 포인트)

아래는 “기능 자체”가 아니라, 도입 시 흔히 부딪히는 운영 포인트입니다.

• 앱 사이즈/메서드 수 증가 가능성
  • 번들링되는 API 범위가 넓을수록 코드 사이즈 영향이 커질 수 있음
• 테스트 범위 확대
  • desugared 구현 + 호출 리라이트가 들어가므로, 단말/OS 조합 테스트 필요
• 리플렉션/클래스 충돌 리스크
  • (특히 java.* / javax.* 접근을 리플렉션으로 다루는 라이브러리 조합에서) 예상치 못한 동작 가능성
• 옵트인 후 옵트아웃이 쉽지 않을 수 있음
  • 여러 모듈/외부 라이브러리가 desugared API 사용에 의존하기 시작하면 되돌리기 비용이 커짐

---

참고(공식 문서/레퍼런스)

• Android Developers: Use Java 8 language features and APIs
• Android Developers Blog: API desugaring (desugar_jdk_libs 스펙/사이즈 영향)
• Android Developers: Java 11+ APIs available through desugaring (지원 API 테이블)
• Google IMA Android SDK release history (3.37.0에서 “app desugaring requirement” 명시)