Kotlin 2.2.x 호환성 가이드

"언어를 현대적으로 유지하기(Keeping the Language Modern)"와 "편안한 업데이트(Comfortable Updates)"는 코틀린 언어 설계의 근본 원칙 중 하나예요. 전자는 언어 진화를 방해하는 구성을 제거해야 한다는 뜻이고, 후자는 코드 마이그레이션이 최대한 매끄럽도록 그 제거를 사전에 잘 공지해야 한다는 뜻이에요.

대부분의 언어 변경은 업데이트 체인지로그나 컴파일러 경고 같은 다른 채널을 통해 이미 공지됐지만, 이 문서가 그것들을 모두 정리해서 Kotlin 2.1에서 Kotlin 2.2로 마이그레이션하기 위한 완전한 참고 자료를 제공할게요.

출처: 공식문서 - Compatibility guide for Kotlin 2.2.x

기본 용어

이 문서에서는 여러 종류의 호환성을 소개해요.

소스(source): 소스 비호환 변경은 (오류나 경고 없이) 잘 컴파일되던 코드가 더 이상 컴파일되지 않게 만드는 변경이에요.
바이너리(binary): 두 바이너리 산출물을 서로 교체해도 로딩이나 링크 오류가 생기지 않으면 두 바이너리가 바이너리 호환된다고 말해요.
동작(behavioral): 같은 프로그램이 변경 전과 후에 서로 다른 동작을 보이면 그 변경은 동작 비호환(behavioral-incompatible)이라고 해요.

이 정의들은 순수한 코틀린에만 적용된다는 점을 기억하세요. 다른 언어(예컨대 자바) 관점에서의 코틀린 코드 호환성은 이 문서의 범위 밖이에요.

언어 (Language)

`-language-version`에서 1.6과 1.7 지원 제거

이슈: KT-71793
컴포넌트: Compiler
비호환 변경 유형: source

간단 요약: Kotlin 2.2부터 컴파일러는 -language-version=1.6 또는 -language-version=1.7을 더 이상 지원하지 않아요. 즉 1.8보다 오래된 언어 기능 집합은 더 이상 지원되지 않아요. 다만 언어 자체는 Kotlin 1.0과 완전히 하위 호환을 유지해요.

폐기 주기(Deprecation cycle):

2.1.0: 버전 1.6과 1.7을 -language-version으로 쓸 때 경고를 보고.
2.2.0: 버전 1.8과 1.9를 -language-version으로 쓸 때 경고를 보고; 1.6과 1.7 버전에 대해서는 경고를 오류로 승격.

애너테이션이 달린 람다에 기본으로 invokedynamic 활성화

이슈: KTLC-278
컴포넌트: Core language
비호환 변경 유형: behavioral

간단 요약: 애너테이션이 달린 람다는 이제 기본적으로 LambdaMetafactory를 통한 invokedynamic을 사용해요. 이로써 동작이 자바 람다와 정렬돼요. 이는 생성된 람다 클래스에서 애너테이션을 가져오는 데 의존하던 리플렉션 기반 코드에 영향을 줘요. 이전 동작으로 되돌리려면 -Xindy-allow-annotated-lambdas=false 컴파일러 옵션을 사용하세요.

폐기 주기:

2.2.0: 애너테이션이 달린 람다에 대해 invokedynamic을 기본으로 활성화.

K2에서 확장 타입에 변성(variance)이 있는 타입 별칭에 대한 생성자 호출과 상속 금지

이슈: KTLC-4
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: out 같은 변성 수정자를 사용하는 타입으로 확장되는 타입 별칭을 통한 생성자 호출과 상속은 K2 컴파일러에서 더 이상 지원되지 않아요. 이는 원래 타입을 쓰면 허용되지 않던 사용이 타입 별칭을 통해서는 허용되던 불일치를 해결해요. 마이그레이션하려면 필요한 곳에서 원래 타입을 명시적으로 사용하세요.

폐기 주기:

2.0.0: 변성 수정자가 있는 타입으로 확장되는 타입 별칭에 대한 생성자 호출이나 슈퍼타입 사용에 경고를 보고.
2.2.0: 경고를 오류로 승격.

코틀린 getter에서 생성된 합성 속성(synthetic properties) 금지

이슈: KTLC-272
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: 코틀린에 정의된 getter에 대해서는 합성 속성이 더 이상 허용되지 않아요. 이는 자바 클래스가 코틀린 클래스를 상속하거나 java.util.LinkedHashSet 같은 매핑된 타입으로 작업할 때 영향을 줘요. 마이그레이션하려면 속성 접근을 해당 getter 함수 호출로 바꾸세요.

폐기 주기:

2.0.0: 코틀린 getter에서 생성된 합성 속성 접근에 경고를 보고.
2.2.0: 경고를 오류로 승격.

JVM에서 인터페이스 함수의 기본 메서드 생성 방식 변경

이슈: KTLC-269
컴포넌트: Core language
비호환 변경 유형: binary

간단 요약: 인터페이스에 선언된 함수는 달리 설정하지 않는 한 이제 JVM 기본 메서드(default methods)로 컴파일돼요. 이로 인해 무관한 슈퍼타입들이 충돌하는 구현을 정의할 때 자바 코드에서 컴파일 오류가 발생할 수 있어요. 이 동작은 이제 폐기된 -Xjvm-default 옵션을 대체하는 안정된 -jvm-default 컴파일러 옵션으로 제어해요. 기본 구현이 DefaultImpls 클래스와 서브클래스에만 생성되던 이전 동작으로 되돌리려면 -jvm-default=disable을 사용하세요.

폐기 주기:

2.2.0: -jvm-default 컴파일러 옵션이 기본으로 enable로 설정.

애너테이션 속성(annotation properties)에 field-타겟 애너테이션 금지

이슈: KTLC-7
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: field-타겟 애너테이션은 애너테이션 속성에 더 이상 허용되지 않아요. 이 애너테이션들은 관찰 가능한 효과가 없었지만, 이 변경은 그에 의존하던 커스텀 IR 플러그인에 영향을 줄 수 있어요. 마이그레이션하려면 속성에서 field-타겟 애너테이션을 제거하세요.

폐기 주기:

2.1.0: @JvmField 애너테이션이 애너테이션 속성에서 경고와 함께 폐기.
2.1.20: 애너테이션 속성의 모든 field-타겟 애너테이션에 경고를 보고.
2.2.0: 경고를 오류로 승격.

타입 별칭(type aliases)에서 reified 타입 매개변수 금지

이슈: KTLC-5
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: reified 수정자는 타입 별칭의 타입 매개변수에 더 이상 허용되지 않아요. reified 타입 매개변수는 인라인 함수에서만 유효하므로, 타입 별칭에서 쓰는 건 효과가 없었어요. 마이그레이션하려면 typealias 선언에서 reified 수정자를 제거하세요.

폐기 주기:

2.1.0: 타입 별칭의 reified 타입 매개변수에 경고를 보고.
2.2.0: 경고를 오류로 승격.

`Number`와 `Comparable`에 대한 인라인 값 클래스 타입 검사 수정

이슈: KTLC-21
컴포넌트: Kotlin/JVM
비호환 변경 유형: behavioral

간단 요약: 인라인 값 클래스는 이제 is와 as 검사에서 java.lang.Number나 java.lang.Comparable의 구현체로 취급되지 않아요. 이 검사들은 박싱된 인라인 클래스에 적용될 때 이전에 잘못된 결과를 돌려줬어요. 이 최적화는 이제 원시 타입과 그 래퍼에만 적용돼요.

폐기 주기:

2.2.0: 새 동작을 활성화.

간접 의존성(indirect dependencies)에서 접근 불가능한 제네릭 타입 금지

이슈: KTLC-3
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: K2 컴파일러는 이제 컴파일러에 보이지 않는 간접 의존성의 타입을 사용할 때 오류를 보고해요. 이는 람다 매개변수나 제네릭 타입 인자처럼 참조된 타입이 누락된 의존성 때문에 사용 불가능한 경우에 영향을 줘요.

폐기 주기:

2.0.0: 람다의 접근 불가능한 제네릭 타입과 선택된 접근 불가능한 제네릭 타입 인자 사용에 오류를 보고; 람다의 접근 불가능한 비-제네릭 타입과 표현식·슈퍼 타입의 접근 불가능한 타입 인자에 경고를 보고.
2.1.0: 람다의 접근 불가능한 비-제네릭 타입에 대한 경고를 오류로 승격.
2.2.0: 표현식 타입의 접근 불가능한 타입 인자에 대한 경고를 오류로 승격.

타입 매개변수 경계(bounds)에 대한 가시성 검사 강제

이슈: KTLC-274
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: 함수와 속성은 이제 선언 자체보다 더 제한적인 가시성을 가진 타입 매개변수 경계를 더 이상 사용할 수 없어요. 이는 이전에는 오류 없이 컴파일되다가 어떤 경우엔 런타임 실패나 IR 검증 오류로 이어지던, 접근 불가능한 타입을 간접적으로 노출하는 것을 방지해요.

폐기 주기:

2.1.0: 타입 매개변수가 선언의 가시성 범위에서 보이지 않는 경계를 가질 때 경고를 보고.
2.2.0: 경고를 오류로 승격.

비-private 인라인 함수에서 private 타입 노출 시 오류 보고

이슈: KT-70916
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: 비-private 인라인 함수에서 private 타입, 함수 또는 속성에 접근하는 것은 더 이상 허용되지 않아요. 마이그레이션하려면 private 엔티티 참조를 피하거나, 함수를 private으로 만들거나, inline 수정자를 제거하세요. inline 제거는 바이너리 호환성을 깨뜨린다는 점을 유의하세요.

폐기 주기:

2.2.0: 비-private 인라인 함수에서 private 타입이나 멤버에 접근할 때 오류를 보고.

매개변수 기본값으로 사용되는 람다에서 non-local return 금지

이슈: KTLC-286
컴포넌트: Core language
비호환 변경 유형: source

간단 요약: 매개변수의 기본값으로 사용되는 람다에서는 non-local return 문이 더 이상 허용되지 않아요. 이 패턴은 이전에 컴파일되긴 했지만 런타임 크래시로 이어졌어요. 마이그레이션하려면 non-local return을 피하도록 람다를 다시 쓰거나, 로직을 기본값 밖으로 옮기세요.

폐기 주기:

2.2.0: 매개변수의 기본값으로 사용되는 람다의 non-local return에 오류를 보고.

표준 라이브러리 (Standard library)

`kotlin.native.Throws` 폐기

이슈: KT-72137
컴포넌트: Kotlin/Native
비호환 변경 유형: source

간단 요약: kotlin.native.Throws가 폐기됐어요. 공통(common) kotlin.Throws 애너테이션을 대신 사용하세요.

폐기 주기:

1.9.0: kotlin.native.Throws를 쓸 때 경고를 보고.
2.2.0: 경고를 오류로 승격.

`AbstractDoubleTimeSource` 폐기

이슈: KT-72137
컴포넌트: kotlin-stdlib
비호환 변경 유형: source

간단 요약: AbstractDoubleTimeSource가 폐기됐어요. AbstractLongTimeSource를 대신 사용하세요.

폐기 주기:

1.8.20: AbstractDoubleTimeSource를 쓸 때 경고를 보고.
2.2.0: 경고를 오류로 승격.

도구 (Tools)

`KotlinCompileTool`의 `setSource()` 함수가 소스를 대체하도록 수정

이슈: KT-59632
컴포넌트: Gradle
비호환 변경 유형: behavioral

간단 요약: KotlinCompileTool 인터페이스의 setSource() 함수는 이제 소스를 추가하는 대신 설정된 소스를 대체해요. 기존 소스를 대체하지 않고 추가하고 싶다면 source() 함수를 사용하세요.

폐기 주기:

2.2.0: 새 동작을 활성화.

`KotlinCompilationOutput#resourcesDirProvider` 속성 폐기

이슈: KT-70620
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: KotlinCompilationOutput#resourcesDirProvider 속성이 폐기됐어요. 추가 리소스 디렉터리를 추가하려면 Gradle 빌드 스크립트에서 KotlinSourceSet.resources를 대신 사용하세요.

폐기 주기:

2.1.0: KotlinCompilationOutput#resourcesDirProvider가 경고와 함께 폐기.
2.2.0: 경고를 오류로 승격.

`BaseKapt.annotationProcessorOptionProviders` 속성 폐기

이슈: KT-58009
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: BaseKapt.annotationProcessorOptionProviders 속성이 BaseKapt.annotationProcessorOptionsProviders를 위해 폐기됐어요. 후자는 MutableList<Any> 대신 ListProperty<CommandLineArgumentProvider>를 받아요. 이로써 기대하는 요소 타입을 명확히 정의하고, 중첩 리스트 같은 잘못된 요소를 추가해 발생하는 런타임 실패를 방지해요. 현재 코드가 리스트를 단일 요소로 추가한다면 add() 함수를 addAll() 함수로 바꾸세요.

폐기 주기:

2.2.0: API에서 새 타입을 강제.

`kotlin-android-extensions` 플러그인 폐기

이슈: KT-72341
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: kotlin-android-extensions 플러그인이 폐기됐어요. Parcelable 구현 생성기에는 별도의 kotlin-parcelize 플러그인을, 합성 뷰(synthetic views)에는 Android Jetpack의 뷰 바인딩(view bindings)을 대신 사용하세요.

폐기 주기:

1.4.20: 플러그인 폐기.
2.1.20: 설정 오류가 도입되고, 플러그인 코드가 실행되지 않음.
2.2.0: 플러그인 코드 제거.
2.4.0: 플러그인 ID 제거.

`kotlinOptions` DSL 폐기

이슈: KT-54110
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: kotlinOptions DSL과 관련 KotlinCompile<KotlinOptions> 태스크 인터페이스를 통해 컴파일러 옵션을 설정하는 기능이 새 compilerOptions DSL을 위해 폐기됐어요. 이 폐기의 일환으로 kotlinOptions 인터페이스의 모든 속성도 이제 각각 폐기 처리돼요. 마이그레이션하려면 compilerOptions DSL을 사용해 컴파일러 옵션을 설정하세요. 마이그레이션 지침은 "Migrate from kotlinOptions {} to compilerOptions {}" 문서를 참고하세요.

폐기 주기:

2.0.0: kotlinOptions DSL에 대해 경고를 보고.
2.2.0: 경고를 오류로 승격하고 kotlinOptions의 모든 속성을 폐기.

`kotlin.incremental.useClasspathSnapshot` 속성 제거

이슈: KT-62963
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: kotlin.incremental.useClasspathSnapshot Gradle 속성이 제거됐어요. 이 속성은 Kotlin 1.8.20부터 기본적으로 활성화된 클래스패스 기반 접근 방식으로 대체된, 폐기된 JVM history 기반 증분 컴파일 모드를 제어했어요.

폐기 주기:

2.0.20: kotlin.incremental.useClasspathSnapshot 속성을 경고와 함께 폐기.
2.2.0: 속성 제거.

코틀린 스크립팅 폐기

이슈: KT-71685, KT-75632, KT-76196.
컴포넌트: Scripting
비호환 변경 유형: source

간단 요약: Kotlin 2.2.0은 다음에 대한 지원을 폐기해요.

REPL: kotlinc를 통해 REPL을 계속 사용하려면 -Xrepl 컴파일러 옵션으로 옵트인하세요.
JSR-223: JSR이 Withdrawn 상태이기 때문이에요. JSR-223 구현은 언어 버전 1.9에서 계속 동작하지만, 미래에 K2 컴파일러로 마이그레이션할 계획은 없어요.
KotlinScriptMojo Maven 플러그인: 계속 사용하면 컴파일러 경고가 보일 거예요.

자세한 내용은 우리 블로그 포스트를 참고하세요.

폐기 주기:

2.1.0: kotlinc에서 REPL 사용을 경고와 함께 폐기.
2.2.0: kotlinc를 통해 REPL을 쓰려면 -Xrepl 컴파일러 옵션으로 옵트인; JSR-223 폐기(언어 버전 1.9로 전환하면 지원 복원 가능); KotlinScriptMojo Maven 플러그인 폐기.
2.4.0: KotlinScriptMojo Maven 플러그인을 통한 코틀린 스크립트 실행 제거.

모호성 분류자(disambiguation classifier) 속성 폐기

이슈: KT-58231
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: 코틀린 Gradle 플러그인이 소스 집합 이름과 IDE 임포트를 어떻게 모호성 분류하는지 제어하던 옵션들이 더 이상 쓰이지 않게 됐어요. 그래서 KotlinTarget 인터페이스에서 다음 속성들이 이제 폐기돼요.

useDisambiguationClassifierAsSourceSetNamePrefix
overrideDisambiguationClassifierOnIdeImport

폐기 주기:

2.0.0: Gradle 속성이 사용될 때 경고를 보고.
2.1.0: 이 경고를 오류로 승격.
2.2.0: Gradle 속성 제거.

공통화(commonization) 매개변수 폐기

이슈: KT-75161
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: 실험적인 공통화 모드용 매개변수가 코틀린 Gradle 플러그인에서 폐기됐어요. 이 매개변수들은 캐시되는 잘못된 컴파일 산출물을 만들 수 있어요. 영향을 받은 산출물을 삭제하려면:

gradle.properties 파일에서 다음 옵션을 제거하세요.

kotlin.mpp.enableOptimisticNumberCommonization
kotlin.mpp.enablePlatformIntegerCommonization

~/.konan/*/klib/commonized 디렉터리의 공통화 캐시를 지우거나 다음 명령을 실행하세요.

./gradlew cleanNativeDistributionCommonization

폐기 주기:

2.2.0: 공통화 매개변수를 오류와 함께 폐기.
2.2.20: 공통화 매개변수 제거.

레거시 메타데이터 컴파일 지원 폐기

이슈: KT-61817
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: 계층적 구조를 설정하고 공통(common)과 중간(intermediate) 소스 집합 사이에 중간 소스 집합을 만들던 옵션들이 더 이상 쓰이지 않게 됐어요. 다음 컴파일러 옵션이 제거돼요.

isCompatibilityMetadataVariantEnabled
withGranularMetadata
isKotlinGranularMetadataEnabled

폐기 주기:

2.2.0: 코틀린 Gradle 플러그인에서 컴파일러 옵션 제거.

`KotlinCompilation.source` API 폐기

이슈: KT-64991
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: 코틀린 소스 집합을 코틀린 컴파일에 직접 추가할 수 있게 하던 KotlinCompilation.source API 접근이 폐기됐어요.

폐기 주기:

1.9.0: KotlinCompilation.source가 사용될 때 경고를 보고.
1.9.20: 이 경고를 오류로 승격.
2.2.0: 코틀린 Gradle 플러그인에서 KotlinCompilation.source 제거; 사용하려 하면 빌드스크립트 컴파일 중 "unresolved reference" 오류가 발생.

타깃 프리셋(target presets) API 폐기

이슈: KT-71698
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: 코틀린 멀티플랫폼 타깃용 타깃 프리셋이 더 이상 쓰이지 않게 됐어요. jvm()이나 iosSimulatorArm64() 같은 타깃 DSL 함수가 이제 같은 사용 사례를 담당해요. 프리셋 관련 API는 모두 폐기됐어요.

org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension의 presets 속성
org.jetbrains.kotlin.gradle.plugin.KotlinTargetPreset 인터페이스와 그 모든 상속자
fromPreset 오버로드들

폐기 주기:

1.9.20: 프리셋 관련 API 사용에 경고를 보고.
2.0.0: 이 경고를 오류로 승격.
2.2.0: 코틀린 Gradle 플러그인의 공개 API에서 프리셋 관련 API 제거; 여전히 사용하는 소스는 "unresolved reference" 오류로 실패하고, 바이너리(예: Gradle 플러그인)는 코틀린 Gradle 플러그인의 최신 버전으로 재컴파일하지 않으면 링크 오류로 실패할 수 있음.

Apple 타깃 단축어(shortcuts) 폐기

이슈: KT-70615
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: ios(), watchos(), tvos() 타깃 단축어가 Kotlin Multiplatform DSL에서 폐기됐어요. 이 단축어들은 Apple 타깃용 소스 집합 계층을 부분적으로 만들도록 설계됐어요. Kotlin Multiplatform Gradle 플러그인은 이제 내장된 계층 템플릿(hierarchy template)을 제공해요. 단축어 대신 타깃 목록을 지정하면 플러그인이 그 타깃들을 위한 중간 소스 집합을 자동으로 설정해요.

폐기 주기:

1.9.20: 타깃 단축어 사용에 경고를 보고; 기본 계층 템플릿을 기본값으로 활성화.
2.1.0: 타깃 단축어 사용에 오류를 보고.
2.2.0: Kotlin Multiplatform Gradle 플러그인에서 타깃 단축어 DSL 제거.

`publishAllLibraryVariants()` 함수 폐기

이슈: KT-60623
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: publishAllLibraryVariants() 함수가 폐기됐어요. 이 함수는 Android 타깃의 모든 빌드 변형을 게시하도록 설계됐어요. 특히 여러 flavor와 빌드 타입을 사용할 때 변형 해석(variant resolution)에 문제를 일으킬 수 있어서, 이 접근 방식은 이제 권장되지 않아요. 빌드 변형을 지정하는 publishLibraryVariants() 함수를 대신 사용하세요.

폐기 주기:

2.2.0: publishAllLibraryVariants() 폐기.

`android` 타깃 폐기

이슈: KT-71608
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: 현재 코틀린 DSL에서 android 타깃 이름이 폐기됐어요. androidTarget을 대신 사용하세요.

폐기 주기:

1.9.0: Kotlin Multiplatform 프로젝트에서 android 이름이 쓰일 때 폐기 경고를 도입.
2.1.0: 이 경고를 오류로 승격.
2.2.0: Kotlin Multiplatform Gradle 플러그인에서 android 타깃 DSL 제거.

`CInteropProcess`의 `konanVersion` 폐기

이슈: KT-71069
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: CInteropProcess 태스크의 konanVersion 속성이 폐기됐어요. CInteropProcess.kotlinNativeVersion을 대신 사용하세요.

폐기 주기:

2.1.0: konanVersion 속성이 사용될 때 경고를 보고.
2.2.0: 이 경고를 오류로 승격.
2.3.0: 코틀린 Gradle 플러그인에서 konanVersion 속성 제거.

`CInteropProcess`의 `destinationDir` 폐기

이슈: KT-71068
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: CInteropProcess 태스크의 destinationDir 속성이 폐기됐어요. CInteropProcess.destinationDirectory.set() 함수를 대신 사용하세요.

폐기 주기:

2.1.0: destinationDir 속성이 사용될 때 경고를 보고.
2.2.0: 이 경고를 오류로 승격.
2.3.0: 코틀린 Gradle 플러그인에서 destinationDir 속성 제거.

`kotlinArtifacts` API 폐기

이슈: KT-74953
컴포넌트: Gradle
비호환 변경 유형: source

간단 요약: 실험적인 kotlinArtifacts API가 폐기됐어요. 최종 네이티브 바이너리를 빌드하려면 코틀린 Gradle 플러그인에서 제공되는 현재 DSL을 사용하세요. 마이그레이션에 부족하다면 이 YouTrack 이슈에 코멘트를 남겨 주세요.

폐기 주기:

2.2.0: kotlinArtifacts API가 사용될 때 경고를 보고.
2.3.0: 이 경고를 오류로 승격.

Kotlin 2.2.x 호환성 가이드