Kotlin 2.4.x 互換性ガイド
言語をモダンに保つ および 快適なアップデート は、Kotlin 言語設計における基本原則です。前者は言語の進化を妨げる構文を削除すべきであることを示しており、後者はコードの移行を可能な限りスムーズにするために、その削除を事前に十分に周知すべきであることを示しています。
ほとんどの言語変更は、アップデートの変更履歴やコンパイラの警告など、他のチャネルを通じて既に発表されていますが、このドキュメントではそれらすべてを要約し、Kotlin 2.3 から Kotlin 2.4 への移行のための完全なリファレンスを提供します。このドキュメントには、ツールに関連する変更に関する情報も含まれています。
基本用語
このドキュメントでは、いくつかの種類の互換性を紹介します：
- ソース (source): ソース互換性のない変更により、以前は問題なく（エラーや警告なしで）コンパイルできていたコードがコンパイルできなくなります。
- バイナリ (binary): 2 つのバイナリアーティファクトを入れ替えても、ロードエラーやリンケージエラーが発生しない場合、それらはバイナリ互換であると言われます。
- 振る舞い (behavioral): 変更を適用する前後で、同じプログラムが異なる動作を示す場合、その変更は振る舞いの互換性がないと言われます。
これらの定義は、純粋な Kotlin に対してのみ適用されることに注意してください。他の言語（Java など）の観点からの Kotlin コードの互換性は、このドキュメントの範囲外です。
言語 (Language)
-language-version=1.9 および K1 コンパイラのサポート終了
課題: KT-80590
コンポーネント: コンパイラ
互換性のない変更の種類: ソース
概要: Kotlin 2.4 以降、コンパイラは
-language-version=1.9をサポートしなくなります。その結果、K1 コンパイラはサポートされなくなります。デプロケーションサイクル:
- 2.2.0:
-language-versionに 1.9 を使用した場合に警告を報告- 2.4.0: 警告をエラーに格上げ
Java 型に対するフレキシブルな明示的 Null 許容型引数の禁止
課題: KTLC-284
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 以前、Kotlin から Java API を呼び出す際、コンパイラは明示的に指定された Null 許容型引数をフレキシブルな型（flexible type）引数として扱うことがありました。Kotlin 2.4.0 では、Null 許容型引数に対してこの動作を適用しなくなったため、型安全性を損なう可能性や実行時に失敗する可能性のあるコードに対してコンパイラがエラーを報告するようになります。
デプロケーションサイクル:
- 2.2.0: フレキシブルな型として扱われる明示的に指定された Null 許容型引数に対して警告を報告
- 2.4.0: 警告をエラーに格上げ
明らかに互換性のない型に対する常に false となる is チェックの禁止
課題: KTLC-365
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: チェックされる型が明らかに互換性がないために常に false となる、無意味な
isチェックをコンパイラが禁止するようになりました。これにより、互換性のない型を含む他の操作と動作が一貫するようになります。デプロケーションサイクル:
- 2.0.0: 明らかに互換性のない型を用いた
isチェックに対して警告を報告- 2.4.0: 警告をエラーに格上げ
インライン関数における可視性の低い型および宣言の露出の禁止
課題: KTLC-283
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: コンパイラは、インライン関数自体よりも可視性が低い型や宣言を、インライン関数が露出させることを禁止するようになりました。
デプロケーションサイクル:
- 2.3.0: インライン関数において可視性の低い型および宣言を露出させている場合に警告を報告
- 2.4.0: 警告をエラーに格上げ
アノテーションのデフォルトの使用箇所ターゲット選択の変更
課題: KTLC-391
コンポーネント: 言語コア
互換性のない変更の種類: バイナリ
概要: Kotlin 2.4.0 では、アノテーションをパラメータ、プロパティ、およびフィールドに伝播させるためのデフォルトルールが更新されました。これは、再コンパイル後のアノテーション処理、リフレクション、およびバイナリメタデータに影響を与える可能性があります。使用箇所ターゲット（use-site target）を指定しない場合、コンパイラは適用可能であれば
paramとpropertyを使用し、propertyが適用できない場合にのみfieldを使用するようになりました。
@param:Annotationのように、使用箇所ターゲットを明示的に指定することができます。プロジェクト全体で以前のデフォルトルールを使用するには、ビルドファイルに-Xannotation-default-target=first-onlyを追加してください。デプロケーションサイクル:
- 2.2.0: 新しいデフォルトルールによって選択される使用箇所ターゲットが変化する場合に警告を報告
- 2.4.0: 新しいデフォルトルールを有効化
アクセス不能な型への暗黙的な参照の禁止
課題: KTLC-384
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 間接的な依存関係からアクセス不能な型を暗黙的に参照する宣言を使用すると、エラーが発生するようになりました。
移行するには、アクセス不能な型を宣言しているモジュールへの明示的な依存関係を追加するか、その型を露出させないように中間 API を更新してください。
デプロケーションサイクル:
- 2.3.0: アクセス不能な型への暗黙的な参照に対して警告を報告
- 2.4.0: 警告をエラーに格上げ
Jakarta Null 許容性アノテーションの強制
課題: KTLC-285
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: コンパイラは、
jakarta.annotation.Nullableまたはjakarta.annotation.Nonnullを使用する Java 宣言に対して、Kotlin 側で宣言された Null 許容性を強制するようになりました。これらのアノテーションによって Null 許容とマークされた Java 宣言を、Null 非許容の Kotlin 型に代入しようとすると、コンパイラがエラーを報告します。デプロケーションサイクル:
- 2.2.0: Jakarta Null 許容性アノテーションが付与された Java 宣言における Null 許容性の不一致に対して警告を報告
- 2.4.0: 警告をエラーに格上げ
呼び出し可能参照の修飾子における不適切な位置の型引数の報告
課題: KTLC-388
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: コンパイラは呼び出し可能参照（callable reference）の左辺をチェックし、内部クラスが修飾子の間違った部分に型引数を含んでいる場合に警告を報告するようになりました。
移行するには、各型引数がそれを宣言しているクラスに属するように参照を更新してください。例えば、
Inner<String, Int>::toStringの代わりに完全な型Outer<Int>.Inner<String>::toStringと記述します。デプロケーションサイクル:
- 2.4.0: 呼び出し可能参照の左辺にある型引数が修飾子の別の部分に属している場合に警告を報告
Null 許容な上限境界を持つ具体化された型パラメータからのクラスリテラルに対するエラー報告
課題: KTLC-370
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Null 許容な上限境界を持つ具体化された（reified）型パラメータから型が決定される式に対して
::classを使用すると、コンパイラがエラーを報告するようになりました。そのような式に対して::classを使用する場合は、明示的な Null チェックまたは!!演算子を使用して、まず値を Null 非許容にしてください。デプロケーションサイクル:
- 2.3.0: Null 許容な上限境界を持つ具体化された型パラメータから型が決定される式に対して
::classが使用された場合に警告を報告- 2.4.0: 警告をエラーに格上げ
匿名オブジェクトにおける宣言前の初期化の禁止
課題: KTLC-290
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 匿名オブジェクトの
initブロックにおいて、プロパティを宣言する前にそのプロパティを初期化しようとすると、Kotlin がエラーを報告するようになりました。デプロケーションサイクル:
- 2.2.20: 匿名オブジェクトの
initブロックにおいて、プロパティ宣言の前にプロパティを初期化している場合に警告を報告- 2.4.0: 警告をエラーに格上げ
非抽象 Java sealed クラスを用いた when 式における網羅性の強制
課題: KTLC-366
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 非抽象 Java sealed クラスを用いた
when式を使用する場合、Kotlin は網羅性（exhaustiveness）をより厳格にチェックし、elseブランチまたは sealed クラス自体に一致するブランチを要求するようになりました。以前は、Java sealed クラス自体を直接インスタンス化できる場合であっても、Kotlin はそのようなwhen式を網羅的であるとして扱うことがありました。デプロケーションサイクル:
- 2.3.0: 非抽象 Java sealed クラスを用いた非網羅的な
when式に対して警告を報告- 2.4.0: 警告をエラーに格上げ
パラメータが多すぎる getValue() および setValue() 関数への operator 修飾子の付与禁止
課題: KTLC-289
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要:
getValue()またはsetValue()関数にoperator修飾子を付与する場合、コンパイラはそれらが必要な数の値パラメータを持っているかどうかをチェックするようになりました。getValue()関数は正確に 2 つの値パラメータを持つ必要があり、setValue()関数は正確に 3 つである必要があります。移行するには、operator修飾子を削除するか、関数のシグネチャを変更してください。デプロケーションサイクル:
- 2.2.20: 値パラメータが多すぎる
operatorgetValue()およびsetValue()関数に対して警告を報告- 2.4.0: 警告をエラーに格上げ
ジェネリック呼び出しにおける一貫性のない型引数の禁止
課題: KTLC-373
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: ジェネリック呼び出しで型引数を指定する際、ある型引数が別の型引数に依存する上限境界制約に違反している場合に、コンパイラがエラーを報告するようになりました。型パラメータが互いに依存している場合は、それらの制約に一致する型引数を使用してください。例えば、
Container<Alpha, BetaKey>()の代わりにContainer<Alpha, AlphaKey>()を使用します。デプロケーションサイクル:
- 2.3.0: ジェネリック呼び出しにおける明示的な型引数が型パラメータ間の上限境界制約に違反している場合に警告を報告
- 2.4.0: 警告をエラーに格上げ
javaClass プロパティへの参照の非推奨化
課題: KTLC-375
コンポーネント: Kotlin/JVM
互換性のない変更の種類: ソース
概要: Kotlin 2.4.0 では、
::class.javaとの混同を避けるため、javaClassプロパティへのプロパティ参照が非推奨になりました。オブジェクトの実行時の Java クラスを取得するには.javaClassを、Java クラス参照を取得するには::class.javaを使用してください。デプロケーションサイクル:
- 2.4.0:
javaClassプロパティへのプロパティ参照に対して警告を報告
オプトインが必要な暗黙的な列挙型コンストラクタ呼び出しのエラー報告
課題: KTLC-359
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 列挙型のエントリが、オプトインを必要とする列挙型のプライマリコンストラクタを暗黙的に呼び出している場合、Kotlin がエラーを報告するようになりました。移行するには、列挙型クラス、またはコンストラクタを呼び出す各列挙型エントリに
@OptInを追加してください。デプロケーションサイクル:
- 2.2.20: 列挙型のエントリがオプトインを必要とする列挙型のプライマリコンストラクタを暗黙的に呼び出している場合に警告を報告
- 2.4.0: 警告をエラーに格上げ
列挙型エントリにおける inline 修飾子の禁止
課題: KTLC-361
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 列挙型のエントリに
inline修飾子を使用すると、Kotlin がエラーを報告するようになりました。デプロケーションサイクル:
- 2.3.0: 列挙型のエントリに
inline修飾子が使用されている場合に警告を報告- 2.4.0: 警告をエラーに格上げ
アノテーション呼び出しおよびパラメータのデフォルト値以外での配列リテラルの禁止
課題: KTLC-369
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: アノテーション呼び出しおよびアノテーションパラメータのデフォルト値以外で配列リテラルを使用すると、エラーが発生するようになりました。移行するには、
arrayOf(...)を使用してください。例えば、Roles(["admin", "user"])の代わりにRoles(arrayOf("admin", "user"))と記述します。デプロケーションサイクル:
- 2.3.0: アノテーション呼び出しおよびアノテーションパラメータのデフォルト値以外での配列リテラル使用に対して警告を報告
- 2.4.0: 警告をエラーに格上げ
CLI コンパイラモードにおける _root_ide_package_ の禁止
課題: KTLC-378
コンポーネント: コンパイラ
互換性のない変更の種類: ソース
概要: CLI コンパイラモードにおいて、IDE 専用の
_root_ide_package_修飾子を使用すると、エラーが発生するようになりました。デプロケーションサイクル:
- 2.3.20: CLI コンパイラモードにおける
_root_ide_package_参照に対して警告を報告- 2.4.0: 警告をエラーに格上げ
可変長引数変換を伴う関数参照の等価性の修正
課題: KTLC-385
コンポーネント: Kotlin/JVM
互換性のない変更の種類: 振る舞い
概要: Kotlin/JVM は、異なる変換を伴う関数参照を「等しくない」ものとして扱うようになりました。以前、Kotlin/JVM は、同じ関数参照が別の変換も使用している場合に等価性チェックにおいて可変長引数（vararg）変換を無視していました。そのため、片方だけが可変長引数変換を使用している場合でも
getDefault(::foo) == getDefaultAndVararg(::foo)がtrueを返すことがありました。デプロケーションサイクル:
- 2.4.0: 新しい動作を導入
コンパニオンオブジェクトへのアクセスに対するオプトインの強制
課題: KTLC-386
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: クラス名参照がオプトインを必要とするコンパニオンオブジェクトに解決される場合に、Kotlin がオプトインエラーを報告するようになりました。例えば、
Cがオプトインアノテーションの付いたコンパニオンオブジェクトに解決される場合、val p = Cにはオプトインが必要になります。デプロケーションサイクル:
- 2.3.20: コンパニオンオブジェクトへのアクセスにオプトインが必要な場合に警告を報告
- 2.4.0:
ERRORレベルのオプトイン要件に対して警告をエラーに格上げ
ネストされたジェネリック引数を持つスーパータイプからの型不一致の報告
課題: KTLC-372
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: ネストされたジェネリック引数を持つスーパータイプに関連する型の不一致をコンパイラが検出した際に、エラーを報告するようになりました。以前はコンパイラがこの不一致を見逃すことがあり、後に
ClassCastExceptionで失敗していました。移行するには、レシーバーのジェネリック型に一致する型引数を使用するか、コンパイラが推論できるように明示的な型引数を削除してください。デプロケーションサイクル:
- 2.4.0: ネストされたジェネリック引数を持つスーパータイプに関連する型の不一致に対してエラーを報告
アクセス不能な宣言を含む推論型の禁止
課題: KTLC-363
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 現在のスコープでアクセス不能な宣言を含む推論型（inferred type）を使用すると、エラーが発生するようになりました。
デプロケーションサイクル:
- 2.3.0: 推論型が現在のスコープでアクセスできない宣言を含んでいる場合に警告を報告
- 2.4.0: 警告をエラーに格上げ
標準ライブラリ (Standard library)
kotlin.io.readLine() 関数の非推奨化
課題: KTLC-394
コンポーネント: kotlin-stdlib
互換性のない変更の種類: ソース
概要:
kotlin.io.readLine()関数が非推奨になりました。readLine()!!の代わりにreadln()関数を、readLine()の代わりにreadlnOrNull()関数を使用してください。デプロケーションサイクル:
- 2.4.0:
kotlin.io.readLine()を使用している場合に警告を報告
AbstractCoroutineContextKey および関連 API の非推奨化
課題: KT-84970
コンポーネント: kotlin-stdlib
互換性のない変更の種類: ソース
概要:
AbstractCoroutineContextKeyクラスおよびその関連 API は Kotlin 1.3 から実験的（experimental）でしたが、エラーを誘発しやすいことが判明しました。このため、このクラスと関連するgetPolymorphicElement()およびminusPolymorphicKey()関数は非推奨になりました。デプロケーションサイクル:
- 2.4.0: 非推奨の API を使用している場合に警告を報告
無限の境界に対する Random.nextDouble() のコントラクトの変更
課題: KT-84368
コンポーネント: kotlin-stdlib
互換性のない変更の種類: 振る舞い
概要:
Random.nextDouble(until)のドキュメント化されたコントラクトにより、until境界が有限であることが要求されるようになりました。有限の境界を使用してください。デプロケーションサイクル:
- 2.4.0: 新しい動作を有効化
ツール (Tools)
レガシー Kotlin/JS コンパイラ型選択 API の削除
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: Kotlin 2.4.0 では、レガシー Kotlin/JS コンパイラ型の選択に関連する非推奨の Gradle API が削除されました。
さらに、
KotlinJsCompilerType列挙型およびコンパイラ型パラメータを持つKotlinProjectExtension.js()のオーバーロードも非推奨になりました。移行するには、js()ターゲット宣言からコンパイラ型引数を削除し、代わりにjs {}ブロックを使用してください。デプロケーションサイクル:
- 1.8.0: レガシー Kotlin/JS コンパイラ型の定数を非推奨化
- 2.4.0: 非推奨のレガシーコンパイラ型 API を削除し、
KotlinJsCompilerTypeまたはコンパイラ型パラメータを持つKotlinProjectExtension.js()オーバーロードを使用している場合に警告を報告
Kotlin Android エクステンションにおける sourceSets の非推奨化
課題: KT-74451
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要:
KotlinAndroidProjectExtensionのsourceSetsプロパティが非推奨になりました。移行するには、代わりに Android Gradle プラグインのandroid { sourceSets { ... } }ブロックを通じてソースセットを設定してください。デプロケーションサイクル:
- 2.4.0:
KotlinAndroidProjectExtensionからsourceSetsにアクセスしている場合に警告を報告
Kotlin/Native Apple フレームワークの Consumable な構成の削除
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: Kotlin 2.4.0 では、Kotlin/Native Apple フレームワークを外部向けのアーティファクトとして露出させる、生成された Consumable な Gradle 構成が削除されました。
デプロケーションサイクル:
- 2.4.0: Kotlin/Native Apple フレームワークの Consumable な構成を削除
Kotlin Gradle プラグインから非推奨のタスク、コンパイル、および DSL API を削除
課題: KT-85509
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: Kotlin 2.4.0 では、以下の非推奨の Kotlin Gradle プラグイン API が削除されました。
コンパイルタスク設定 API:
KotlinJvmCompile.parentKotlinOptionsKotlinJvmCompile.moduleNameKotlinJvmFactory.createKotlinJvmOptions()KotlinCompileおよびKotlin2JsCompileタスクのBaseKotlinCompile.moduleNameKotlin マルチプラットフォームの階層およびターゲット API:
DeprecatedKotlinTargetHierarchyDslKotlinMultiplatformExtension.targetHierarchyKotlinTargetComponent.sourcesArtifactsKotlinTarget.sourceSetsKotlinHierarchyBuilder.withoutCompilations()KotlinHierarchyBuilder.filterCompilations()KotlinHierarchyBuilder.withWasm()KotlinCompilation.defaultSourceSetNameKotlin コンパイルタスク API:
KotlinCompilation.compileKotlinTaskProviderKotlinCompilation.compileKotlinTaskKotlin 依存関係ハンドラ API:
KotlinDependencyHandler.enforcedPlatform()KotlinDependencyHandler.platform()その他の非推奨のタスクおよびエクステンション API:KaptExtension.processorsKotlinTest.excludesKotlinTest.fileResolverKotlinTest.execHandleFactoryIncrementalSyncTask.destinationDir移行するには、これらの API の使用を中止し、非推奨の診断メッセージで推奨されている代替手段を使用してください。
デプロケーションサイクル:
- 2.4.0: 非推奨の API を削除
明示的な shrunk クラスパススナップショット設定の非推奨化
課題: KT-75837
コンポーネント: ビルドツール API
互換性のない変更の種類: ソース
概要:
ClasspathSnapshotBasedIncrementalCompilationApproachParametersにおけるshrunkClasspathSnapshot設定パラメータが非推奨になりました。shrunk クラスパススナップショットは内部的な増分コンパイルキャッシュであるため、コンパイラは増分コンパイラメタデータのworkingDirectory配下でこれを自動的に作成および管理するようになりました。移行するには、shrunkClasspathSnapshotに値を渡すのではなく、自動管理されるスナップショットファイルを使用してください。デプロケーションサイクル:
- 2.4.0:
shrunkClasspathSnapshotを使用している場合に警告を報告
冗長な ABI バリデーション Gradle DSL 要素の削除
課題: KT-80685
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: Kotlin 2.4.0 では、ABI バリデーション Gradle DSL が簡素化され、冗長な設定項目が削除されました。移行するには、
abiValidation { legacyDump { ... } }の代わりにabiValidation {}で直接レポート設定を行い、abiValidation { klib { enabled = ... } }を削除し、klib.keepUnsupportedTargetsの代わりにkeepLocallyUnsupportedTargetsを使用してください。デプロケーションサイクル:
- 2.4.0: 冗長な ABI バリデーション DSL 要素を削除
旧式の Compose コンパイラ Gradle プラグインオプションの非推奨化
課題: KT-85343
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: Kotlin 2.4.0 では、以下の非推奨の Compose コンパイラ Gradle プラグインオプションを使用するとエラーが報告されるようになりました。
generateFunctionKeyMetaClassesenableIntrinsicRememberenableNonSkippingGroupOptimizationenableStrongSkippingModestabilityConfigurationFileComposeFeatureFlag.StrongSkippingComposeFeatureFlag.IntrinsicRemember非推奨の機能オプションの代わりに
featureFlagsを、stabilityConfigurationFileの代わりにstabilityConfigurationFilesを使用してください。デプロケーションサイクル:
- 2.0.20:
enableIntrinsicRemember、enableNonSkippingGroupOptimization、およびenableStrongSkippingModeに対して警告を報告- 2.1.0:
stabilityConfigurationFileに対して警告を報告- 2.4.0: 警告をエラーに格上げ
旧式の Kotlin/Native Gradle タスク API に対するエラー報告
課題: KT-85510
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: 以下の非推奨の Kotlin/Native Gradle タスク API を使用するとエラーが報告されるようになりました。
AbstractKotlinNativeCompileのプロパティ:
additionalCompilerOptionslanguageSettingsprogressiveMode
KotlinNativeCompileのプロパティ:
moduleNamekonanDataDirkonanHomelanguageVersionapiVersionenabledLanguageFeaturesoptInAnnotationsInUseadditionalCompilerOptions
CInteropProcessのプロパティ:
outputFilekonanDataDirkonanHomedefFile
KotlinNativeLinkのプロパティ:
languageSettingsadditionalCompilerOptionskonanDataDirkonanHomeさらに、
KotlinNativeLink.compilationプロパティが削除されました。デプロケーションサイクル:
- 2.4.0: 非推奨の Kotlin/Native Gradle タスク API に対してエラーを報告し、
KotlinNativeLink.compilationプロパティを削除