Kotlin 2.0.x 호환성 가이드

Keep the Language Modern과 Comfortable Updates는 Kotlin 언어 설계의 기본 원칙 두 가지예요. 전자는 언어 진화를 막는 구조는 제거해야 한다는 뜻이고, 후자는 그런 제거를 미리 잘 알려서 코드 마이그레이션을 최대한 매끄럽게 해야 한다는 뜻이에요.

대부분의 언어 변경은 이미 업데이트 변경 로그나 컴파일러 경고 같은 다른 채널을 통해 안내됐지만, 이 문서는 Kotlin 1.9에서 2.0으로 마이그레이션할 때 참고할 수 있는 완전한 레퍼런스를 제공해요.

Kotlin K2 컴파일러가 Kotlin 2.0의 일부로 도입됐어요. 새 컴파일러의 장점, 마이그레이션 중 마주칠 수 있는 변경 사항, 이전 컴파일러로 되돌리는 방법은 K2 컴파일러 마이그레이션 가이드를 참고하세요.

출처: Kotlin 문서 — Compatibility guide for Kotlin 2.0.x

본문

기본 용어

이 문서에서는 몇 가지 종류의 호환성을 다뤄요.

source(소스): 소스 비호환 변경은 예전에는 (경고나 오류 없이) 잘 컴파일되던 코드가 더 이상 컴파일되지 않게 만드는 변경이에요.
binary(바이너리): 두 바이너리 아티팩트를 서로 바꿔 써도 로딩이나 링크 오류가 나지 않으면 바이너리 호환이라고 불러요.
behavioral(동작): 같은 프로그램이 변경 적용 전후에 다르게 동작한다면 동작 비호환 변경이라고 해요.

이 정의는 순수 Kotlin에만 해당한다는 점 기억해 두세요. 다른 언어(예를 들어 Java) 관점에서 본 Kotlin 코드의 호환성은 이 문서의 범위 밖이에요.

언어

프로젝션된 리시버에서 합성 setter 사용 deprecated 처리

Issue: KT-54309

Component: Core language

Incompatible change type: source

Short summary: Java 클래스의 합성 setter를 사용해 그 클래스의 프로젝션된 타입과 충돌하는 타입을 할당하면 오류가 발생해요.

Deprecation cycle:

1.8.20: 합성 프로퍼티 setter가 반변 위치에 프로젝션된 파라미터 타입을 가져 호출 지점 인자 타입을 호환되지 않게 만들면 경고를 보고해요.
2.0.0: 경고를 오류로 올려요.

Java 하위클래스에서 오버로드된 inline 클래스 파라미터를 가진 함수를 호출할 때 맹글링 수정

Issue: KT-56545

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

2.0.0: 함수 호출에서 올바른 맹글링 동작을 사용해요. 이전 동작으로 되돌리려면 -XXLanguage:-MangleCallsToJavaMethodsWithValueClasses 컴파일러 옵션을 사용해요.

반변 캡처 타입에 대한 올바른 타입 근사 알고리즘

Issue: KT-49404

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.8.20: 문제가 되는 호출에 대해 경고를 보고해요.
2.0.0: 경고를 오류로 올려요.

프로퍼티 초기화 전에 프로퍼티 값에 접근하는 것 금지

Issue: KT-56408

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 영향받는 맥락에서 프로퍼티가 초기화 전에 접근되면 오류를 보고해요.

같은 이름의 가져온 클래스에 모호성이 있을 때 오류 보고

Issue: KT-57750

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 스타 임포트로 가져온 여러 패키지에 있는 클래스 이름을 해석할 때 오류를 보고해요.

Kotlin 람다를 기본적으로 invokedynamic과 LambdaMetafactory로 생성

Issue: KT-45375

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

2.0.0: 새 동작을 구현해요. 람다가 기본적으로 invokedynamic과 LambdaMetafactory를 사용해 생성돼요.

식이 필요한 곳에서 분기가 하나뿐인 if 조건 금지

Issue: KT-57871

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: if 조건에 분기가 하나뿐이면 오류를 보고해요.

제네릭 타입의 스타 프로젝션을 전달해 자기 상한을 위반하는 것 금지

Issue: KT-61718

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 제네릭 타입의 스타 프로젝션을 전달해 자기 상한이 위반되면 오류를 보고해요.

private inline 함수의 반환 타입에서 익명 타입 근사

Issue: KT-54862

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.9.0: 추론된 반환 타입에 익명 타입이 포함돼 있으면 private inline 함수에 대해 경고를 보고해요.
2.0.0: 그런 private inline 함수의 반환 타입을 상위 타입으로 근사해요.

로컬 함수형 타입 프로퍼티의 invoke 규약보다 로컬 확장 함수 호출을 우선하도록 오버로드 해석 동작 변경

Issue: KT-37592

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

2.0.0: 새 오버로드 해석 동작. 함수 호출이 invoke 규약보다 일관되게 우선해요.

바이너리 의존성의 상위 타입 변경으로 상속 멤버 충돌이 생길 때 오류 보고

Issue: KT-51194

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.7.0: 바이너리 의존성의 상위 타입에서 상속 멤버 충돌이 발생한 선언에 대해 CONFLICTING_INHERITED_MEMBERS_WARNING 경고를 보고해요.
2.0.0: 경고를 오류(CONFLICTING_INHERITED_MEMBERS)로 올려요.

불변 타입의 파라미터에서 @UnsafeVariance 어노테이션 무시

Issue: KT-57609

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 동작을 구현해요. 반변 파라미터의 타입 불일치에 대한 오류를 보고할 때 @UnsafeVariance 어노테이션을 무시해요.

호출 밖의 companion 객체 멤버 참조에 대한 타입 변경

Issue: KT-54316

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.8.20: companion 객체 함수 참조 타입이 unbound 참조로 추론되면 경고를 보고해요.
2.0.0: 모든 사용 맥락에서 companion 객체 함수 참조가 bound 참조로 추론되도록 동작을 변경해요.

private inline 함수에서 익명 타입 노출 금지

Issue: KT-33917

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.3.0: private inline 함수에서 반환된 익명 객체의 자체 멤버 호출에 대해 경고를 보고해요.
2.0.0: 그런 private inline 함수의 반환 타입을 상위 타입으로 근사하고, 익명 객체 멤버 호출은 해석하지 않아요.

while 루프 break 이후의 안전하지 않은 스마트 캐스트에 대해 오류 보고

Issue: KT-22379

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 동작을 구현해요. 언어 버전 1.9로 전환하면 예전 동작을 복원할 수 있어요.

교차 타입의 변수에 그 교차 타입의 하위 타입이 아닌 값을 할당할 때 오류 보고

Issue: KT-53752

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 교차 타입을 가진 변수에 그 교차 타입의 하위 타입이 아닌 값이 할당되면 오류를 보고해요.

opt-in이 필요한 메서드를 포함한 SAM 생성자로 만들어진 인터페이스에 opt-in 요구

Issue: KT-52628

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.7.20: SAM 생성자를 통한 OptIn 사용에 대해 경고를 보고해요.
2.0.0: SAM 생성자를 통한 OptIn 사용에 대해 경고를 오류로 올려요(OptIn 마커 심각도가 경고면 계속 경고를 보고해요).

typealias 생성자에서 상한 위반 금지

Issue: KT-54066

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.8.0: typealias 생성자에서 상한이 위반되는 경우에 대해 경고를 도입해요.
2.0.0: K2 컴파일러에서 경고를 오류로 올려요.

구조 분해 변수의 실제 타입을 명시적 타입과 일치시키기

Issue: KT-57011

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 동작을 구현해요. 구조 분해 변수의 실제 타입이 명시적 타입이 지정된 경우 그 타입과 일치하게 돼요.

opt-in이 필요한 기본값을 가진 파라미터 타입이 있는 생성자를 호출할 때 opt-in 요구

Issue: KT-55111

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.8.20: opt-in이 필요한 파라미터 타입을 가진 생성자 호출에 대해 경고를 보고해요.
2.0.0: 경고를 오류로 올려요(OptIn 마커 심각도가 경고면 계속 경고를 보고해요).

같은 스코프 수준에서 같은 이름의 프로퍼티와 enum entry 사이의 모호성 보고

Issue: KT-52802

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.7.20: 컴파일러가 같은 스코프 수준에서 enum entry 대신 프로퍼티로 해석하면 경고를 보고해요.
2.0.0: K2 컴파일러에서 같은 스코프 수준의 같은 이름의 프로퍼티와 enum entry를 모두 마주치면 모호성을 보고해요(예전 컴파일러에서는 경고를 그대로 둬요).

enum entry보다 companion 프로퍼티를 선호하도록 한정자 해석 동작 변경

Issue: KT-47310

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 해석 동작을 구현해요. companion 프로퍼티가 enum entry보다 우선해요.

invoke 호출 리시버 타입과 invoke 함수 타입을 desugared 형태로 작성된 것처럼 해석

Issue: KT-58260

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: invoke 호출 리시버 타입과 invoke 함수 타입을 desugared 형태로 작성된 것처럼 독립적으로 해석해요.

비공개 inline 함수를 통해 private 클래스 멤버 노출 금지

Issue: KT-55179

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.9.0: internal inline 함수에서 private 클래스 companion 객체 멤버를 호출하면 PRIVATE_CLASS_MEMBER_FROM_INLINE_WARNING 경고를 보고해요.
2.0.0: 이 경고를 PRIVATE_CLASS_MEMBER_FROM_INLINE 오류로 올려요.

프로젝션된 제네릭 타입에서 절대 non-null 타입의 nullability 수정

Issue: KT-54663

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 동작을 구현해요. 프로젝션된 타입이 모든 in-place not-null 타입을 고려해요.

전위 증가의 추론된 타입을 inc() 연산자의 반환 타입 대신 getter의 반환 타입과 일치하도록 변경

Issue: KT-57178

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 동작을 구현해요. 전위 증가의 추론된 타입이 inc() 연산자의 반환 타입 대신 getter의 반환 타입과 일치하도록 변경돼요.

상위클래스에 선언된 제네릭 내부 클래스에서 내부 클래스를 상속할 때 바운드 검사 강제

Issue: KT-61749

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 제네릭 내부 상위클래스 타입 파라미터의 상한이 위반되면 오류를 보고해요.

예상 타입이 함수 타입 파라미터를 가진 함수 타입일 때 SAM 타입이 있는 callable 참조 할당 금지

Issue: KT-64342

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 예상 타입이 함수 타입 파라미터를 가진 함수 타입일 때 SAM 타입이 있는 callable 참조에 대해 컴파일 오류를 보고해요.

companion 객체의 어노테이션 해석에 companion 객체 스코프 고려

Issue: KT-64299

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

2.0.0: 새 동작을 구현해요. companion 객체의 어노테이션 해석에서 companion 객체 스코프가 더 이상 무시되지 않아요.

안전 호출과 규약 연산자의 조합에 대한 평가 의미 변경

Issue: KT-41034

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

1.4.0: 잘못된 호출 각각에 대해 경고를 보고해요.
2.0.0: 새 해석 동작을 구현해요.

backing field가 있고 사용자 정의 setter가 있는 프로퍼티의 즉시 초기화 요구

Issue: KT-58589

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

1.9.20: 기본 생성자가 없는 경우에 대해 MUST_BE_INITIALIZED 경고를 도입해요.
2.0.0: 경고를 오류로 올려요.

invoke 연산자 규약 호출에서 임의 표현식에 대한 Unit 변환 금지

Issue: KT-61182

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

2.0.0: 변수 및 invoke 해석에서 임의 표현식에 Unit 변환이 적용되면 오류를 보고해요. 영향받는 표현식에서 이전 동작을 유지하려면 -XXLanguage:+UnitConversionsOnArbitraryExpressions 컴파일러 옵션을 사용해요.

안전 호출로 접근하는 non-null Java 필드에 nullable 할당 금지

Issue: KT-62998

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: nullable이 non-null Java 필드에 할당되면 오류를 보고해요.

raw 타입 파라미터를 포함한 Java 메서드를 오버라이드할 때 스타 프로젝션된 타입 요구

Issue: KT-57600

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 동작을 구현해요. raw 타입 파라미터에 대한 오버라이드를 금지해요.

V에 companion이 있을 때 (V)::foo 참조 해석 변경

Issue: KT-47313

Component: Core language

Incompatible change type: behavioral

Deprecation cycle:

1.6.0: 현재 companion 객체 인스턴스에 bound된 callable 참조에 대해 경고를 보고해요.
2.0.0: 새 동작을 구현해요. 타입에 괄호를 추가해도 더 이상 타입의 companion 객체 인스턴스에 대한 참조가 되지 않아요.

사실상 public inline 함수에서 암시적 non-public API 접근 금지

Issue: KT-54997

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.8.20: public inline 함수에서 암시적 non-public API에 접근하면 컴파일 경고를 보고해요.
2.0.0: 경고를 오류로 올려요.

프로퍼티 getter에서 use-site get 어노테이션 금지

Issue: KT-57422

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.9.0: getter의 use-site get 어노테이션에 대해 경고(progressive 모드에서는 오류)를 보고해요.
2.0.0: 경고를 INAPPLICABLE_TARGET_ON_PROPERTY 오류로 올려요. -XXLanguage:-ProhibitUseSiteGetTargetAnnotations을 사용하면 경고로 되돌릴 수 있어요.

빌더 추론 람다 함수에서 타입 파라미터가 상한으로 암시적으로 추론되는 것 방지

Issue: KT-47986

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.7.20: 타입 인자의 타입 파라미터를 선언된 상한으로 추론할 수 없으면 경고(또는 progressive 모드에서는 오류)를 보고해요.
2.0.0: 경고를 오류로 올려요.

공개 시그니처에서 로컬 타입을 근사할 때 nullability 유지

Issue: KT-53982

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.8.0: flexible 타입을 flexible 상위 타입으로 근사해요. 선언이 nullable이어야 하는데 non-nullable 타입으로 추론되면 경고를 보고하고 NPE를 피하려고 타입을 명시적으로 지정하도록 안내해요.
2.0.0: nullable 타입을 nullable 상위 타입으로 근사해요.

스마트 캐스팅 목적의 false && ... 및 false || ... 특수 처리 제거

Issue: KT-65776

Component: Core language

Incompatible change type: source

Deprecation cycle:

2.0.0: 새 동작을 구현해요. false && ...과 false || ...에 대한 특수 처리가 없어요.

enum의 inline open 함수 금지

Issue: KT-34372

Component: Core language

Incompatible change type: source

Deprecation cycle:

1.8.0: enum의 inline open 함수에 대해 경고를 보고해요.
2.0.0: 경고를 오류로 올려요.

도구

Gradle의 가시성 변경

Issue: KT-64653

Component: Gradle

Incompatible change type: source

Short summary: 이전에는 특정 DSL 맥락을 위한 Kotlin DSL 함수와 프로퍼티가 의도치 않게 다른 DSL 맥락으로 새어 나가곤 했어요. 우리는 @KotlinGradlePluginDsl 어노테이션을 추가해서 Kotlin Gradle 플러그인 DSL 함수와 프로퍼티가 의도하지 않은 수준에 노출되는 것을 막았어요. 다음 수준들이 서로 분리됐어요.

Kotlin 확장
Kotlin 타깃
Kotlin 컴파일
Kotlin 컴파일 태스크

Deprecation cycle:

2.0.0: 대부분의 흔한 경우, 빌드 스크립트가 잘못 구성됐다면 컴파일러가 수정 방법에 대한 제안과 함께 경고를 보고해요. 그 외에는 컴파일러가 오류를 보고해요.

kotlinOptions DSL deprecated 처리

Issue: KT-63419

Component: Gradle

Incompatible change type: source

Short summary: kotlinOptions DSL과 관련 KotlinCompile<KotlinOptions> 태스크 인터페이스를 통해 컴파일러 옵션을 구성하는 기능이 deprecated 처리됐어요.

Deprecation cycle:

2.0.0: 경고를 보고해요.

KotlinCompilation DSL의 compilerOptions deprecated 처리

Issue: KT-65568

Component: Gradle

Incompatible change type: source

Short summary: KotlinCompilation DSL에서 compilerOptions 프로퍼티를 구성하는 기능이 deprecated 처리됐어요.

Deprecation cycle:

2.0.0: 경고를 보고해요.

CInteropProcess 처리의 예전 방식 deprecated 처리

Issue: KT-62795

Component: Gradle

Incompatible change type: source

Short summary: CInteropProcess 태스크와 CInteropSettings 클래스가 이제 defFile과 defFileProperty 대신 definitionFile 프로퍼티를 사용해요.

이로 인해 defFile이 동적으로 생성될 때 CInteropProcess 태스크와 defFile을 생성하는 태스크 사이에 추가 dependsOn 관계를 둘 필요가 없어져요.

Kotlin/Native 프로젝트에서 Gradle은 이제 빌드 과정 후반에 연결된 태스크가 실행된 뒤 definitionFile 프로퍼티의 존재를 지연해서 검증해요.

Deprecation cycle:

2.0.0: defFile과 defFileProperty 파라미터가 deprecated 처리돼요.
2.4.0: deprecated defFile 프로퍼티에 대해 오류를 보고해요.

kotlin.useK2 Gradle 프로퍼티 제거

Issue: KT-64379

Component: Gradle

Incompatible change type: behavioral

Short summary: kotlin.useK2 Gradle 프로퍼티가 제거됐어요. Kotlin 1.9.*에서는 이 프로퍼티로 K2 컴파일러를 활성화할 수 있었어요. Kotlin 2.0.0 이후에서는 K2 컴파일러가 기본으로 활성화되므로 이 프로퍼티는 효과가 없고 이전 컴파일러로 되돌리는 데도 쓸 수 없어요.

Deprecation cycle:

1.8.20: kotlin.useK2 Gradle 프로퍼티가 deprecated 처리돼요.
2.0.0: kotlin.useK2 Gradle 프로퍼티가 제거돼요.

deprecated 플랫폼 플러그인 ID 제거

Issue: KT-65187

Component: Gradle

Incompatible change type: source

Short summary: 다음 플랫폼 플러그인 ID에 대한 지원이 제거됐어요.

kotlin-platform-android
kotlin-platform-jvm
kotlin-platform-js
org.jetbrains.kotlin.platform.android
org.jetbrains.kotlin.platform.jvm
org.jetbrains.kotlin.platform.js

Deprecation cycle:

1.3: 플랫폼 플러그인 ID가 deprecated 처리돼요.
2.0.0: 플랫폼 플러그인 ID가 더 이상 지원되지 않아요.

outputFile JavaScript 컴파일러 옵션 제거

Issue: KT-61116

Component: Gradle

Incompatible change type: source

Short summary: outputFile JavaScript 컴파일러 옵션이 제거됐어요. 대신 Kotlin2JsCompile 태스크의 destinationDirectory 프로퍼티를 사용해 컴파일된 JavaScript 출력 파일이 쓰이는 디렉터리를 지정할 수 있어요.

Deprecation cycle:

1.9.25: outputFile 컴파일러 옵션이 deprecated 처리돼요.
2.0.0: outputFile 컴파일러 옵션이 제거돼요.

Kotlin 2.0.x 호환성 가이드