From cf0a2fbaf132eabdbb56fbf2fca5f53dabaf165f Mon Sep 17 00:00:00 2001 From: Danil Pavlov Date: Wed, 19 Feb 2025 16:04:34 +0100 Subject: [PATCH] feat: Kotlin 2.1.20-RC release (#4707) --- docs/kr.tree | 2 +- docs/labels.list | 3 +- docs/topics/eap.md | 8 +- .../multiplatform-compatibility-guide.md | 63 ++++++- docs/topics/whatsnew-eap.md | 173 +++++++++++++++--- docs/v.list | 4 +- 6 files changed, 213 insertions(+), 40 deletions(-) diff --git a/docs/kr.tree b/docs/kr.tree index 9fffb7721f0..4da0afe60ea 100644 --- a/docs/kr.tree +++ b/docs/kr.tree @@ -24,7 +24,7 @@ - + diff --git a/docs/labels.list b/docs/labels.list index a8a9988c2af..0d879d6eac7 100644 --- a/docs/labels.list +++ b/docs/labels.list @@ -8,6 +8,7 @@ The feature is in Alpha. It may change incompatibly and require manual migration in the future. The feature is in Beta. It is almost stable, but migration steps may be required in the future. We'll do our best to minimize any changes you have to make. + This functionality is available only in the latest EAP version. - This functionality is available only in the latest EAP version. + This functionality is available only in the latest EAP version. \ No newline at end of file diff --git a/docs/topics/eap.md b/docs/topics/eap.md index e14dbddd6d9..5bc4432ae57 100644 --- a/docs/topics/eap.md +++ b/docs/topics/eap.md @@ -43,13 +43,13 @@ In this channel, you can also get notifications about new EAP builds. Build highlights - 2.1.20-Beta2 -

Released: January 29, 2025

-

Release on GitHub

+ 2.1.20-RC +

Released: February 19, 2025

+

Release on GitHub

A tooling release with K2 kapt enabled by default.

-

For more details, please refer to the changelog or What's new in Kotlin 2.1.20-Beta2.

+

For more details, please refer to the changelog or What's new in Kotlin 2.1.20-RC.

\ No newline at end of file diff --git a/docs/topics/multiplatform/multiplatform-compatibility-guide.md b/docs/topics/multiplatform/multiplatform-compatibility-guide.md index 2219f797860..0d2550eb3c4 100644 --- a/docs/topics/multiplatform/multiplatform-compatibility-guide.md +++ b/docs/topics/multiplatform/multiplatform-compatibility-guide.md @@ -37,6 +37,56 @@ When configuring your project, check the compatibility of a particular version o This section covers incompatible changes that end their deprecation cycle and come into effect in Kotlin 2.0.0−%kotlinVersion%. + +### Java source sets created by default + + +**What's changed?** + +To align Kotlin Multiplatform with upcoming changes in Gradle, we are phasing out the `withJava()` function. The `withJava()` +function enabled integration with Gradle's Java plugins by creating the necessary Java source sets. From Kotlin %kotlinEapVersion%, +these Java source sets are created by default. + +**What's the best practice now?** + +Previously, you had to explicitly use the `withJava()` function to create `src/jvmMain/java` and `src/jvmTest/java` source sets: + +```kotlin +kotlin { + jvm { + withJava() + } +} +``` + +From Kotlin %kotlinEapVersion%, you can remove the `withJava()` function from your build script. + +In addition, Gradle now only runs Java compile tasks if Java sources are present, triggering a JVM validation +diagnostic that previously didn't run before. This diagnostic fails if you explicitly configure an incompatible JVM target +for `KotlinJvmCompile` tasks or inside `compilerOptions`. For guidance on ensuring JVM target compatibility, see +[Check for JVM target compatibility of related compile tasks](gradle-configure-project.md#check-for-jvm-target-compatibility-of-related-compile-tasks). + +If your project uses Gradle versions higher than 8.7 and doesn't rely on Gradle Java plugins, like [Java](https://docs.gradle.org/current/userguide/java_plugin.html), +[Java Library](https://docs.gradle.org/current/userguide/java_library_plugin.html), or [Application](https://docs.gradle.org/current/userguide/application_plugin.html), +or a third party Gradle plugin that has a dependency on a Gradle Java plugin, you can remove the `withJava()` function. + +If your project uses the [Application](https://docs.gradle.org/current/userguide/application_plugin.html) Gradle Java plugin, +we recommend migrating to the [new Experimental DSL](whatsnew-eap.md#kotlin-multiplatform-new-dsl-to-replace-gradle-s-application-plugin). +Starting with Gradle 8.7, the Application plugin will no longer work with the Kotlin Multiplatform Gradle plugin. + +If you want to use both the Kotlin Multiplatform Gradle plugin and other Gradle plugins for +Java in your multiplatform project, see [Deprecated compatibility with Kotlin Multiplatform Gradle plugin and Java plugins](multiplatform-compatibility-guide.md#deprecated-compatibility-with-kotlin-multiplatform-gradle-plugin-and-gradle-java-plugins). + +If you run into any issues, report them in our [issue tracker](https://kotl.in/issue) or ask for help in our [public Slack channel](https://kotlinlang.slack.com/archives/C19FD9681). + +**When do the changes take effect?** + +Here's the planned deprecation cycle: + +* Gradle >8.6: introduce a deprecation warning for any previous version of Kotlin in multiplatform projects using the `withJava()` function. +* Gradle 9.0: raise this warning to an error. +* %kotlinEapVersion%: introduce a deprecation warning when using the `withJava()` function with any version of Gradle. + ### Rename of `android` target to `androidTarget` @@ -633,7 +683,7 @@ Here's the planned deprecation cycle: * 1.3.40: introduce a warning when `targetPresets.jvmWithJava` is used * 1.9.20: raise this warning to an error -* >1.9.20: remove `targetPresets.jvmWithJava` API; attempts to use it lead to the buildscript compilation failure +* >1.9.20: remove `targetPresets.jvmWithJava` API; attempts to use it lead to the buildscript compilation failure > Even though the whole `targetPresets` API is deprecated, the `jvmWithJava` preset has a different deprecation timeline. > @@ -764,6 +814,7 @@ declarations. Also, it's now only possible to import forward declarations by usi This section covers incompatible changes that end their deprecation cycle and come into effect in Kotlin 1.7.0−1.8.22. + ### Deprecated compatibility with Kotlin Multiplatform Gradle plugin and Gradle Java plugins {initial-collapse-state="collapsed" collapsible="true"} **What's changed?** @@ -805,7 +856,7 @@ If you see this deprecation warning in your multiplatform project, we recommend Otherwise, if you want to use both the Kotlin Multiplatform Gradle plugin and these Gradle plugins for Java in your multiplatform project, we recommend that you: -1. Create a separate subproject in your multiplatform project. +1. Create a separate subproject in your Gradle project. 2. In the separate subproject, apply the Gradle plugin for Java. 3. In the separate subproject, add a dependency on your parent multiplatform project. @@ -814,7 +865,7 @@ project, we recommend that you: {style="warning"} For example, you have a multiplatform project called `my-main-project` and you want -to use the [Application](https://docs.gradle.org/current/userguide/application_plugin.html) Gradle plugin to run a JVM application. +to use the [Java Library](https://docs.gradle.org/current/userguide/java_library_plugin.html) Gradle plugin. Once you've created a subproject, let's call it `subproject-A`, your parent project structure should look like this: @@ -828,14 +879,14 @@ Once you've created a subproject, let's call it `subproject-A`, your parent proj └── Main.java ``` -In your subproject's `build.gradle.kts` file, apply the Application plugin in the `plugins {}` block: +In your subproject's `build.gradle.kts` file, apply the Java Library plugin in the `plugins {}` block: ```kotlin plugins { - id("application") + id("java-library") } ``` @@ -844,7 +895,7 @@ plugins { ```groovy plugins { - id('application') + id('java-library') } ``` diff --git a/docs/topics/whatsnew-eap.md b/docs/topics/whatsnew-eap.md index 598cc83809d..50108542ef8 100644 --- a/docs/topics/whatsnew-eap.md +++ b/docs/topics/whatsnew-eap.md @@ -14,8 +14,12 @@ Here are some details of this EAP release: * [](#kotlin-k2-compiler-new-default-kapt-plugin) * [](#kotlin-multiplatform-new-dsl-to-replace-gradle-s-application-plugin) +* [](#kotlin-native-new-inlining-optimization) +* [Kotlin/Wasm: migration to Provider API](#kotlin-wasm-migration-to-provider-api-for-kotlin-wasm-and-kotlin-js-properties) +* [Gradle: support for custom publication variants](#support-for-adding-custom-gradle-publication-variants) * [](#common-atomic-types) * [](#changes-in-uuid-parsing-and-formatting-functions) +* [](#compose-compiler-source-information-included-by-default) ## IDE support @@ -32,12 +36,12 @@ See [Update to a new release](releases.md#update-to-a-new-kotlin-version) for de Starting with Kotlin %kotlinEapVersion%, the K2 implementation of the kapt compiler plugin is enabled by default for all the projects. -The JetBrains team has launched the new implementation of the kapt plugin with the K2 compiler back in Kotlin 1.9.20. -Since then, we have further developed K2 kapt's internal implementation and made its behavior similar to that of K1 kapt, -while significantly improving its performance. +The JetBrains team launched the new implementation of the kapt plugin with the K2 compiler back in Kotlin 1.9.20. +Since then, we have further developed the internal implementation of K2 kapt and made its behavior similar to that of +the K1 version, while significantly improving its performance as well. If you encounter any issues when using kapt with the K2 compiler, -you can temporarily revert to the previous kapt plugin implementation. +you can temporarily revert to the previous plugin implementation. To do this, add the following option to the `gradle.properties` file of your project: @@ -45,7 +49,7 @@ To do this, add the following option to the `gradle.properties` file of your pro kapt.use.k2=false ``` -Please report such issues to our [issue tracker](https://youtrack.jetbrains.com/issue/KT-71439/K2-kapt-feedback). +Please report any issues to our [issue tracker](https://youtrack.jetbrains.com/issue/KT-71439/K2-kapt-feedback). ## Kotlin Multiplatform: new DSL to replace Gradle's Application plugin @@ -100,14 +104,116 @@ plugin is applied on the first `executable {}` block. If you run into any issues, report them in our [issue tracker](https://kotl.in/issue) or let us know in our [public Slack channel](https://kotlinlang.slack.com/archives/C19FD9681). -## Gradle: support for version 8.11 +## Kotlin/Native: new inlining optimization + + +Kotlin %kotlinEapVersion% introduces a new inlining optimization pass, which comes before the actual code generation +phase. + +The new inlining pass in the Kotlin/Native compiler should perform better than the standard LLVM inliner and improve the +runtime performance of the generated code. + +The new inlining pass is currently [Experimental](components-stability.md#stability-levels-explained). To try it out, +use the following compiler option: + +```none +-Xbinary=preCodegenInlineThreshold=40 +``` + +Our experiments show that 40 is a good compromise threshold for the optimization. According to our benchmarks, this +gives an overall performance improvement of 9.5%. Of course, you can try out other values, too. + +If you experience increased binary size or compilation time, please report such issues +in [YouTrack](https://kotl.in/issue). + +## Kotlin/Wasm: migration to Provider API for Kotlin/Wasm and Kotlin/JS properties + +Previously, properties in Kotlin/Wasm and Kotlin/JS extensions were mutable (`var`) and assigned directly in build +scripts: + +```kotlin +the().version = "2.0.0" +``` + +Now, properties are exposed through the [Provider API](https://docs.gradle.org/current/userguide/properties_providers.html), +and you must use the `.set()` function to assign values: + +```kotlin +the().version.set("2.0.0") +``` + +The Provider API ensures that values are lazily computed and properly integrated with task dependencies, improving build +performance. + +With this change, direct property assignments are deprecated in favor of `*EnvSpec` classes, +such as `NodeJsEnvSpec` and `YarnRootEnvSpec`. + +Additionally, several alias tasks have been removed to avoid confusion: + +| Deprecated task | Replacement | +|------------------------|-----------------------------------------------------------------| +| `wasmJsRun` | `wasmJsBrowserDevelopmentRun` | +| `wasmJsBrowserRun` | `wasmJsBrowserDevelopmentRun` | +| `wasmJsNodeRun` | `wasmJsNodeDevelopmentRun` | +| `wasmJsBrowserWebpack` | `wasmJsBrowserProductionWebpack` or `wasmJsBrowserDistribution` | +| `jsRun` | `jsBrowserDevelopmentRun` | +| `jsBrowserRun` | `jsBrowserDevelopmentRun` | +| `jsNodeRun` | `jsNodeDevelopmentRun` | +| `jsBrowserWebpack` | `jsBrowserProductionWebpack` or `jsBrowserDistribution` | + +If you only use Kotlin/JS or Kotlin/Wasm in build scripts, no action is required as Gradle automatically handles +assignments. + +However, if you maintain a plugin based on the Kotlin Gradle Plugin, and your plugin does not apply `kotlin-dsl`, you +must update property assignments to use the `.set()` function. + +## Gradle +### Support for version 8.11 Kotlin %kotlinEapVersion% is now compatible with the latest stable Gradle version, 8.11, and supports its features. -Gradle versions 8.7 to 8.11 are supported, with one exception. If you use the Kotlin Multiplatform Gradle plugin, -you may see deprecation warnings in your multiplatform projects when calling the [`withJava()` function in the JVM target](multiplatform-dsl-reference.md#jvm-targets). -We plan to fix this issue as soon as possible. -For more information, see the related issue in [YouTrack](https://youtrack.jetbrains.com/issue/KT-66542). +### Support for adding custom Gradle publication variants + + +Kotlin %kotlinEapVersion% introduces support for adding custom [Gradle publication variants](https://docs.gradle.org/current/userguide/variant_attributes.html). +This feature is available for multiplatform projects and projects targeting the JVM. + +> You cannot modify existing Gradle variants with this feature. +> +{style="note"} + +This feature is [Experimental](components-stability.md#stability-levels-explained). To opt in, +use the `@OptIn(ExperimentalKotlinGradlePluginApi::class)` annotation or the compiler option +`-opt-in=kotlin.ExperimentalKotlinGradlePluginApi`. + +To add a custom Gradle publication variant, invoke the `adhocSoftwareComponent()` function, which returns an instance +of [`AdhocComponentWithVariants`](https://docs.gradle.org/current/javadoc/org/gradle/api/component/AdhocComponentWithVariants.html) +that you can configure in the Kotlin DSL: + +```kotlin +plugins { + // Only JVM and Multiplatform are supported + kotlin("jvm") + // or + kotlin("multiplatform") +} + +kotlin { + @OptIn(ExperimentalKotlinGradlePluginApi::class) + publishing { + // Returns an instance of AdhocSoftwareComponent + adhocSoftwareComponent() + // Alternatively, you can configure AdhocSoftwareComponent in the DSL block as follows + adhocSoftwareComponent { + // Add your custom variants here using the AdhocSoftwareComponent API + } + } +} +``` + +> For more information on variants, see Gradle's [Customizing publishing guide](https://docs.gradle.org/current/userguide/publishing_customization.html). +> +{style="tip"} ## Standard library @@ -153,14 +259,14 @@ suspend fun main() { println("Total processed items: ${processedItems.load()}") } ``` -{validate="false" kotlin-runnable="true" kotlin-min-compiler-version="2.1.20-beta2"} +{validate="false" kotlin-runnable="true" kotlin-min-compiler-version="2.1.20"} To enable seamless interoperability between Kotlin's atomic types and Java's [`java.util.concurrent.atomic`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html) atomic types, the API provides the `.asJavaAtomic()` and `.asKotlinAtomic()` extension functions. On the JVM, Kotlin -atomics and Java atomics are the same types in runtime, so you can transform Java atomics to Kotlin atomics and the other -way around without any overhead. +atomics and Java atomics are the same types in runtime, so you can transform Java atomics into Kotlin atomics and vice +versa without any overhead. -Let's look at an example that shows how Kotlin and Java atomic types can work together: +Here's an example that shows how Kotlin and Java atomic types can work together: ```kotlin // Imports the necessary libraries @@ -183,7 +289,7 @@ fun main() { } //sampleEnd ``` -{validate="false" kotlin-runnable="true" kotlin-min-compiler-version="2.1.20-beta2"} +{validate="false" kotlin-runnable="true" kotlin-min-compiler-version="2.1.20"} ### Changes in UUID parsing and formatting functions @@ -191,17 +297,17 @@ fun main() { The JetBrains team continues to improve the support for UUIDs [introduced to the standard library in 2.0.20](whatsnew2020.md#support-for-uuids-in-the-common-kotlin-standard-library). Previously, the `parse()` function only accepted UUIDs in the hex-and-dash format. With Kotlin %kotlinEapVersion%, -you can use `parse()` for _both_ the hex-and-dash and the plain hexadecimal format (without dashes). +you can use `parse()` for _both_ the hex-and-dash and the plain hexadecimal (without dashes) formats. -We also introduce functions specific to the operations with the hex-and-dash format in this release: +We've also introduced functions specific to operations with the hex-and-dash format in this release: -* `parseHexDash()` that parses UUIDs from the hex-and-dash format. -* `toHexDashString()` that converts a UUID into a string in the hex-and-dash format (mirroring the `toString()` functionality). +* `parseHexDash()` parses UUIDs from the hex-and-dash format. +* `toHexDashString()` converts a `Uuid` into a `String` in the hex-and-dash format (mirroring the functionality of `toString()`). These functions work similarly to [`parseHex()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.uuid/-uuid/-companion/parse-hex.html) -and [`toHexString()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.uuid/-uuid/to-hex-string.html) that were -introduced earlier for the hexadecimal format. Explicit naming for the parsing and formatting functionality should improve -code clarity and your overall experience with UUID handling. +and [`toHexString()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.uuid/-uuid/to-hex-string.html), which were +introduced earlier for the hexadecimal format. Explicit naming for parsing and formatting functionality should improve +code clarity and your overall experience with UUIDs. Remember that the UUID support in the standard library is still [Experimental](components-stability.md#stability-levels-explained). To opt in, use the `@ExperimentalUuidApi` annotation or the compiler option `-opt-in=kotlin.uuid.ExperimentalUuidApi`: @@ -213,17 +319,32 @@ import kotlin.uuid.Uuid //sampleStart @OptIn(ExperimentalUuidApi::class) fun main() { - // Use parse() to accept a UUID in a plain hexadecimal format + // parse() accepts a UUID in a plain hexadecimal format val uuid = Uuid.parse("550e8400e29b41d4a716446655440000") - // Convert it to the hex-and-dash format + // Converts it to the hex-and-dash format val hexDashFormat = uuid.toHexDashString() + + // Outputs the UUID in the hex-and-dash format println(hexDashFormat) - // Output: 550e8400-e29b-41d4-a716-446655440000 } //sampleEnd ``` -{validate="false" kotlin-runnable="true" kotlin-min-compiler-version="2.1.20-beta2"} +{validate="false" kotlin-runnable="true" kotlin-min-compiler-version="2.1.20"} + +## Compose compiler: source information included by default + +The Compose compiler Gradle plugin enables [including source information](https://kotlinlang.org/api/kotlin-gradle-plugin/compose-compiler-gradle-plugin/org.jetbrains.kotlin.compose.compiler.gradle/-compose-compiler-gradle-plugin-extension/include-source-information.html) +by default on all platforms. The `includeSourceInformation` option was already enabled for Android, this change aligns +the plugin behavior across platforms and allows support for new runtime features. + +Remember to check if you set this option using `freeCompilerArgs`: when used along with the plugin, it can fail the +build due to an option being set twice. + +## Breaking changes and deprecations + +To align Kotlin Multiplatform with upcoming changes in Gradle, we are phasing out the `withJava()` function. +[Java source sets are now created by default](multiplatform-compatibility-guide.md#java-source-sets-created-by-default). ## How to update to Kotlin %kotlinEapVersion% diff --git a/docs/v.list b/docs/v.list index d83a344e146..8e60491bc0b 100644 --- a/docs/v.list +++ b/docs/v.list @@ -13,8 +13,8 @@ - - + +