Kotlin 2.0.x 호환성 가이드

_언어의 현대성 유지(Keeping the Language Modern)_와 _편안한 업데이트(Comfortable Updates)_는 코틀린 언어 설계의 기본 원칙입니다. 전자는 언어의 진화를 방해하는 구문을 제거해야 함을 의미하며, 후자는 코드 마이그레이션을 최대한 원활하게 만들기 위해 이러한 제거를 사전에 충분히 안내해야 함을 의미합니다.

대부분의 언어 변경 사항은 업데이트된 변경 로그나 컴파일러 경고와 같은 다른 채널을 통해 이미 발표되었지만, 이 문서는 코틀린 1.9에서 코틀린 2.0으로 마이그레이션하기 위한 전체 참조 가이드를 제공합니다.

코틀린 K2 컴파일러가 코틀린 2.0의 일부로 도입되었습니다. 새 컴파일러의 이점, 마이그레이션 중에 발생할 수 있는 변경 사항 및 이전 컴파일러로 되돌리는 방법에 대한 정보는 K2 컴파일러 마이그레이션 가이드를 참조하세요.

기본 용어

이 문서에서는 여러 종류의 호환성을 소개합니다.

• 소스(source): 소스 비호환 변경은 이전에 정상적으로 컴파일되던(오류나 경고 없이) 코드가 더 이상 컴파일되지 않게 만듭니다.
• 바이너리(binary): 두 바이너리 아티팩트를 서로 교체해도 로딩이나 링크 오류가 발생하지 않는 경우 두 아티팩트가 바이너리 호환된다고 합니다.
• 동작(behavioral): 변경 사항을 적용하기 전과 후에 동일한 프로그램이 서로 다른 동작을 보이는 경우 동작 비호환 변경이라고 합니다.

이러한 정의는 순수 코틀린에 대해서만 제공된다는 점을 기억하세요. 다른 언어의 관점(예: Java)에서 본 코틀린 코드의 호환성은 이 문서의 범위를 벗어납니다.

언어

프로젝션된 리시버에서의 합성 세터 사용 중단

이슈: KT-54309

컴포넌트: 코어 언어

비호환 변경 유형: 소스

요약: Java 클래스의 합성 세터(synthetic setter)를 사용하여 해당 클래스의 프로젝션된 타입(projected type)과 충돌하는 타입을 할당하려고 하면 오류가 발생합니다.

지원 종료 주기:

• 1.8.20: 합성 프로퍼티 세터가 반공변(contravariant) 위치에 프로젝션된 매개변수 타입을 가져 호출 지점의 인자 타입이 호환되지 않는 경우 경고 리포트
• 2.0.0: 경고를 오류로 격상

Java 서브클래스에서 오버로드된 인라인 클래스 매개변수를 가진 함수 호출 시 맹글링 수정

이슈: KT-56545

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 2.0.0: 함수 호출 시 올바른 맹글링(mangling) 동작을 사용합니다. 이전 동작으로 되돌리려면 -XXLanguage:-MangleCallsToJavaMethodsWithValueClasses 컴파일러 옵션을 사용하세요.

반공변 캡처된 타입에 대한 타입 근사 알고리즘 수정

이슈: KT-49404

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.8.20: 문제가 있는 호출에 대해 경고 리포트
• 2.0.0: 경고를 오류로 격상

프로퍼티 초기화 전 프로퍼티 값 접근 금지

이슈: KT-56408

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 영향받는 컨텍스트에서 프로퍼티가 초기화되기 전에 접근되는 경우 오류 리포트

동일한 이름을 가진 임포트된 클래스 간에 모호성이 있는 경우 오류 리포트

이슈: KT-57750

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 스타 임포트(star import)로 임포트된 여러 패키지에 존재하는 클래스 이름을 해석할 때 오류 리포트

기본적으로 invokedynamic 및 LambdaMetafactory를 통해 코틀린 람다 생성

이슈: KT-45375

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 람다는 기본적으로 invokedynamic 및 LambdaMetafactory를 사용하여 생성됩니다.

식이 필요한 경우 브랜치가 하나만 있는 if 조건문 금지

이슈: KT-57871

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: if 조건문에 브랜치가 하나만 있는 경우 오류 리포트

제네릭 타입의 스타 프로젝션을 전달하여 셀프 상한(self upper bounds)을 위반하는 행위 금지

이슈: KT-61718

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 제네릭 타입의 스타 프로젝션을 전달하여 셀프 상한을 위반하는 경우 오류 리포트

프라이빗 인라인 함수의 반환 타입에서 익명 타입 근사 수행

이슈: KT-54862

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.9.0: 추론된 반환 타입에 익명 타입이 포함된 프라이빗 인라인 함수에 대해 경고 리포트
• 2.0.0: 이러한 프라이빗 인라인 함수의 반환 타입을 상위 타입(supertype)으로 근사(approximate) 처리

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

이슈: KT-37592

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 2.0.0: 새로운 오버로드 해소 동작 적용. 함수 호출이 invoke 규칙보다 일관되게 우선순위를 갖습니다.

바이너리 의존성의 상위 타입 변경으로 인해 상속된 멤버 충돌이 발생하는 경우 오류 리포트

이슈: KT-51194

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.7.0: 바이너리 의존성의 상위 타입에서 상속된 멤버 충돌이 발생한 선언에 대해 CONFLICTING_INHERITED_MEMBERS_WARNING 경고 리포트
• 2.0.0: 경고를 오류로 격상: CONFLICTING_INHERITED_MEMBERS

무공변(invariant) 타입의 매개변수에서 @UnsafeVariance 어노테이션 무시

이슈: KT-57609

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 반공변(contravariant) 매개변수의 타입 불일치에 대한 오류를 리포트할 때 @UnsafeVariance 어노테이션을 무시합니다.

컴패니언 객체 멤버의 호출 외부 참조에 대한 타입 변경

이슈: KT-54316

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.8.20: 바인딩되지 않은 참조(unbound reference)로 추론된 컴패니언 객체 함수 참조 타입에 대해 경고 리포트
• 2.0.0: 모든 사용 컨텍스트에서 컴패니언 객체 함수 참조가 바인딩된 참조(bound reference)로 추론되도록 동작 변경

프라이빗 인라인 함수를 통한 익명 타입 노출 금지

이슈: KT-33917

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.3.0: 프라이빗 인라인 함수에서 반환된 익명 객체의 고유 멤버 호출에 대해 경고 리포트
• 2.0.0: 이러한 프라이빗 인라인 함수의 반환 타입을 상위 타입으로 근사하고 익명 객체 멤버에 대한 호출을 해소(resolve)하지 않음

while 루프 break 이후의 불안전한 스마트 캐스트에 대해 오류 리포트

이슈: KT-22379

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 언어 버전을 1.9로 전환하여 이전 동작을 복구할 수 있음

교차 타입 변수에 해당 교차 타입의 하위 타입이 아닌 값이 할당될 때 오류 리포트

이슈: KT-53752

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 교차 타입(intersection type)을 가진 변수에 해당 교차 타입의 하위 타입이 아닌 값이 할당될 때 오류 리포트

SAM 생성자로 구성된 인터페이스에 옵트인이 필요한 메서드가 포함된 경우 옵트인 요구

이슈: KT-52628

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.7.20: SAM 생성자를 통한 OptIn 사용에 대해 경고 리포트
• 2.0.0: SAM 생성자를 통한 OptIn 사용에 대해 경고를 오류로 격상 (단, OptIn 마커 심각도가 경고인 경우 경고로 유지)

타입별칭 생성자에서의 상한 위반 금지

이슈: KT-54066

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.8.0: 타입별칭(typealias) 생성자에서 상한(upper bound)이 위반되는 경우에 대해 경고 도입
• 2.0.0: K2 컴파일러에서 경고를 오류로 격상

명시적 타입이 지정된 경우 구조 분해 변수의 실제 타입을 명시적 타입과 일치시킴

이슈: KT-57011

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 구조 분해 변수의 실제 타입이 명시적으로 지정된 타입과 일치하게 됨

옵트인이 필요한 기본값을 가진 매개변수 타입을 포함한 생성자 호출 시 옵트인 요구

이슈: KT-55111

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.8.20: 옵트인이 필요한 매개변수 타입을 가진 생성자 호출에 대해 경고 리포트
• 2.0.0: 경고를 오류로 격상 (단, OptIn 마커 심각도가 경고인 경우 경고로 유지)

동일한 스코프 레벨에서 동일한 이름을 가진 프로퍼티와 열거형 엔트리 간의 모호성 리포트

이슈: KT-52802

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.7.20: 컴파일러가 동일한 스코프 레벨에서 열거형 엔트리 대신 프로퍼티로 해석할 때 경고 리포트
• 2.0.0: K2 컴파일러에서 동일한 스코프 레벨에 동일한 이름을 가진 프로퍼티와 열거형 엔트리가 모두 있는 경우 모호성 리포트 (이전 컴파일러에서는 경고 유지)

열거형 엔트리보다 컴패니언 프로퍼티를 우선하도록 한정자 해소 동작 변경

이슈: KT-47310

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 해소 동작 구현. 열거형 엔트리보다 컴패니언 프로퍼티를 우선함

invoke 호출 리시버 타입과 invoke 함수 타입을 디슈가링된 형식으로 작성된 것처럼 해소

이슈: KT-58260

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: invoke 호출 리시버 타입과 invoke 함수 타입을 마치 디슈가링(desugared)된 형식으로 작성된 것처럼 각각 독립적으로 해소

비공개 인라인 함수를 통한 프라이빗 클래스 멤버 노출 금지

이슈: KT-55179

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.9.0: 내부 인라인 함수에서 프라이빗 클래스 컴패니언 객체 멤버를 호출할 때 PRIVATE_CLASS_MEMBER_FROM_INLINE_WARNING 경고 리포트
• 2.0.0: 이 경고를 PRIVATE_CLASS_MEMBER_FROM_INLINE 오류로 격상

프로젝션된 제네릭 타입에서 반드시 null이 아닌 타입의 null 허용 여부 수정

이슈: KT-54663

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 프로젝션된 타입이 모든 인플레이스(in-place) null이 아닌 타입을 고려함

접두사 증감 연산자의 추론된 타입을 inc() 연산자의 반환 타입 대신 게터의 반환 타입과 일치하도록 변경

이슈: KT-57178

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 접두사 증감 연산자의 추론된 타입이 inc() 연산자의 반환 타입 대신 게터(getter)의 반환 타입과 일치하도록 변경됨

상위 클래스에 선언된 제네릭 내부 클래스로부터 내부 클래스를 상속받을 때 제약 조건 검사 강제

이슈: KT-61749

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 제네릭 내부 상위 클래스의 타입 매개변수 상한이 위반될 때 오류 리포트

기대되는 타입이 함수 타입 매개변수를 가진 함수 타입인 경우 SAM 타입을 가진 호출 가능 참조 할당 금지

이슈: KT-64342

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 기대되는 타입이 함수 타입 매개변수를 가진 함수 타입일 때, SAM 타입을 가진 호출 가능 참조(callable reference)에 대해 컴파일 오류 리포트

컴패니언 객체의 어노테이션 해소 시 컴패니언 객체 스코프 고려

이슈: KT-64299

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 컴패니언 객체의 어노테이션 해소 시 컴패니언 객체 스코프가 무시되지 않음

안전한 호출과 관례 연산자 조합에 대한 평가 시맨틱 변경

이슈: KT-41034

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 1.4.0: 잘못된 각 호출에 대해 경고 리포트
• 2.0.0: 새로운 해소 동작 구현

백킹 필드와 커스텀 세터가 있는 프로퍼티의 즉시 초기화 요구

이슈: KT-58589

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 1.9.20: 기본 생성자가 없는 경우 MUST_BE_INITIALIZED 경고 도입
• 2.0.0: 경고를 오류로 격상

invoke 연산자 관례 호출 시 임의의 식에 대한 Unit 변환 금지

이슈: KT-61182

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 2.0.0: 변수 및 invoke 해소 시 임의의 식에 Unit 변환이 적용되는 경우 오류 리포트. 영향받는 식에 대해 이전 동작을 유지하려면 -XXLanguage:+UnitConversionsOnArbitraryExpressions 컴파일러 옵션을 사용하세요.

안전한 호출로 필드에 접근할 때 null 허용 값을 null이 아닌 Java 필드에 할당하는 행위 금지

이슈: KT-62998

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: null 허용 값이 null이 아닌 Java 필드에 할당되는 경우 오류 리포트

로우 타입 매개변수를 포함하는 Java 메서드를 오버라이드할 때 스타 프로젝션 타입 요구

이슈: KT-57600

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. 로우 타입(raw type) 매개변수에 대한 오버라이딩 금지

V에 컴패니언이 있을 때 (V)::foo 참조 해소 변경

이슈: KT-47313

컴포넌트: 코어 언어

비호환 변경 유형: 동작

지원 종료 주기:

• 1.6.0: 현재 컴패니언 객체 인스턴스에 바인딩된 호출 가능 참조에 대해 경고 리포트
• 2.0.0: 새로운 동작 구현. 타입 주위에 괄호를 추가해도 더 이상 해당 타입의 컴패니언 객체 인스턴스에 대한 참조가 되지 않음

실질적으로 공개된 인라인 함수에서 암시적 비공개 API 접근 금지

이슈: KT-54997

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.8.20: 공개 인라인 함수에서 암시적 비공개 API에 접근할 때 컴파일 경고 리포트
• 2.0.0: 경고를 오류로 격상

프로퍼티 게터에서의 사용 지점 get 어노테이션 사용 금지

이슈: KT-57422

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.9.0: 게터의 사용 지점(use-site) get 어노테이션에 대해 경고(프로그레시브 모드에서는 오류) 리포트
• 2.0.0: 경고를 INAPPLICABLE_TARGET_ON_PROPERTY 오류로 격상. 경고로 되돌리려면 -XXLanguage:-ProhibitUseSiteGetTargetAnnotations 사용

빌더 추론 람다 함수에서 타입 매개변수가 상한으로 암시적으로 추론되는 현상 방지

이슈: KT-47986

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.7.20: 타입 인자에 대한 타입 매개변수가 선언된 상한으로 추론될 수 없는 경우 경고(또는 프로그레시브 모드에서 오류) 리포트
• 2.0.0: 경고를 오류로 격상

공개 시그니처에서 로컬 타입을 근사할 때 null 허용 여부 유지

이슈: KT-53982

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.8.0: 유연한 타입(flexible types)은 유연한 상위 타입에 의해 근사됨. 선언이 null 허용이어야 함에도 null 허용이 아닌 타입으로 추론되는 경우, NPE를 방지하기 위해 타입을 명시적으로 지정하도록 권장하는 경고 리포트
• 2.0.0: null 허용 타입은 null 허용 상위 타입에 의해 근사됨

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

이슈: KT-65776

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 2.0.0: 새로운 동작 구현. false && ... 및 false || ...에 대한 특수 처리 없음

열거형 내 인라인 open 함수 금지

이슈: KT-34372

컴포넌트: 코어 언어

비호환 변경 유형: 소스

지원 종료 주기:

• 1.8.0: 열거형(enum) 내 인라인 open 함수에 대해 경고 리포트
• 2.0.0: 경고를 오류로 격상

도구

Gradle 가시성 변경

이슈: KT-64653

컴포넌트: Gradle

비호환 변경 유형: 소스

요약: 이전에는 특정 DSL 컨텍스트를 위해 의도된 일부 코틀린 DSL 함수와 프로퍼티가 의도치 않게 다른 DSL 컨텍스트로 노출되었습니다. 코틀린 Gradle 플러그인 DSL 함수와 프로퍼티가 의도하지 않은 레벨에 노출되는 것을 방지하기 위해 @KotlinGradlePluginDsl 어노테이션을 추가했습니다. 다음 레벨들이 서로 분리됩니다.

• 코틀린 확장(extension)
• 코틀린 타겟
• 코틀린 컴파일
• 코틀린 컴파일 태스크

지원 종료 주기:

• 2.0.0: 가장 일반적인 경우, 빌드 스크립트가 잘못 구성되면 컴파일러가 해결 방법이 포함된 경고를 리포트합니다. 그 외의 경우에는 컴파일러가 오류를 리포트합니다.

kotlinOptions DSL 사용 중단

이슈: KT-63419

컴포넌트: Gradle

비호환 변경 유형: 소스

요약: kotlinOptions DSL 및 관련 KotlinCompile<KotlinOptions> 태스크 인터페이스를 통해 컴파일러 옵션을 설정하는 기능이 지원 중단되었습니다.

지원 종료 주기:

• 2.0.0: 경고 리포트

KotlinCompilation DSL에서 compilerOptions 사용 중단

이슈: KT-65568

컴포넌트: Gradle

비호환 변경 유형: 소스

요약: KotlinCompilation DSL에서 compilerOptions 프로퍼티를 설정하는 기능이 지원 중단되었습니다.

지원 종료 주기:

• 2.0.0: 경고 리포트

CInteropProcess 처리의 이전 방식 지원 중단

이슈: KT-62795

컴포넌트: Gradle

비호환 변경 유형: 소스

요약: CInteropProcess 태스크와 CInteropSettings 클래스가 이제 defFile 및 defFileProperty 대신 definitionFile 프로퍼티를 사용합니다.

이를 통해 defFile이 동적으로 생성될 때 CInteropProcess 태스크와 defFile을 생성하는 태스크 사이에 추가적인 dependsOn 관계를 설정할 필요가 없어집니다.

코틀린/네이티브 프로젝트에서 Gradle은 이제 빌드 프로세스의 후반부에서 연결된 태스크가 실행된 후에 definitionFile 프로퍼티의 존재 여부를 지연 확인합니다.

지원 종료 주기:

• 2.0.0: defFile 및 defFileProperty 매개변수 지원 중단

kotlin.useK2 Gradle 프로퍼티 제거

이슈: KT-64379

컴포넌트: Gradle

비호환 변경 유형: 동작

요약: kotlin.useK2 Gradle 프로퍼티가 제거되었습니다. 코틀린 1.9.*에서는 K2 컴파일러를 활성화하는 데 이 프로퍼티를 사용할 수 있었습니다. 코틀린 2.0.0 이상에서는 K2 컴파일러가 기본적으로 활성화되므로, 이 프로퍼티는 아무런 효과가 없으며 이전 컴파일러로 되돌리는 데 사용할 수 없습니다.

지원 종료 주기:

• 1.8.20: kotlin.useK2 Gradle 프로퍼티 지원 중단
• 2.0.0: kotlin.useK2 Gradle 프로퍼티 제거

지원 중단된 플랫폼 플러그인 ID 제거

이슈: KT-65187

컴포넌트: Gradle

비호환 변경 유형: 소스

요약: 다음 플랫폼 플러그인 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

지원 종료 주기:

• 1.3: 해당 플랫폼 플러그인 ID 지원 중단
• 2.0.0: 해당 플랫폼 플러그인 ID를 더 이상 지원하지 않음

outputFile JavaScript 컴파일러 옵션 제거

이슈: KT-61116

컴포넌트: Gradle

비호환 변경 유형: 소스

요약: outputFile JavaScript 컴파일러 옵션이 제거되었습니다. 대신 Kotlin2JsCompile 태스크의 destinationDirectory 프로퍼티를 사용하여 컴파일된 JavaScript 출력 파일이 작성될 디렉토리를 지정할 수 있습니다.

지원 종료 주기:

• 1.9.25: outputFile 컴파일러 옵션 지원 중단
• 2.0.0: outputFile 컴파일러 옵션 제거