K2 编译器迁移指南

As the Kotlin language and ecosystem have continued to evolve, so has the Kotlin compiler. The first step was the introduction of the new JVM and JS IR (Intermediate Representation) backends that share logic, simplifying code generation for targets on different platforms. Now, the next stage of its evolution brings a new frontend known as K2.

With the arrival of the K2 compiler, the Kotlin frontend has been completely rewritten and features a new, more efficient architecture. The fundamental change the new compiler brings is the use of one unified data structure that contains more semantic information. This frontend is responsible for performing semantic analysis, call resolution, and type inference.

The new architecture and enriched data structure enables the K2 compiler to provide the following benefits:

• Improved call resolution and type inference. The compiler behaves more consistently and understands your code better.
• Easier introduction of syntactic sugar for new language features. In the future, you'll be able to use more concise, readable code when new features are introduced.
• Faster compilation times. Compilation times can be significantly faster.

• Enhanced IDE performance. If you enable K2 Kotlin mode in IntelliJ IDEA, then IntelliJ IDEA will use the K2 compiler frontend to analyze your Kotlin code, bringing stability and performance improvements. For more information, see Support in IntelliJ IDEA.

  The K2 Kotlin mode is in Alpha. The performance and stability of code highlighting and code completion have been improved, but not all IDE features are supported yet.

Thanks to the new K2 compiler, we've already made improvements to some language features.

This guide:

• Explains the benefits of the new K2 compiler.
• Highlights changes you might encounter during migration and how to adapt your code accordingly.
• Describes how you can roll back to the previous version.

The new K2 compiler is enabled by default starting with 2.0.0-RC3. For more information on the new features provided in Kotlin 2.0.0, as well as the new K2 compiler, see What's new in Kotlin 2.0.0-RC3.

Language feature improvements

The Kotlin K2 compiler improves language features related to smart-casting and Kotlin Multiplatform.

Smart casts

The Kotlin compiler can automatically cast an object to a type in specific cases, saving you the trouble of having to explicitly specify it yourself. This is called smart-casting. The Kotlin K2 compiler now performs smart casts in even more scenarios than before.

In Kotlin 2.0.0, we've made improvements related to smart casts in the following areas:

• Local variables and further scopes
• Type checks with the logical or operator
• Inline functions
• Properties with function types
• Exception handling
• Increment and decrement operators

Local variables and further scopes

Previously, if a variable was evaluated as not null within an if condition, the variable would be smart-cast. Information about this variable would then be shared further within the scope of the if block.

However, if you declared the variable outside the if condition, no information about the variable would be available within the if condition, so it couldn't be smart-cast. This behavior was also seen with when expressions and while loops.

From Kotlin 2.0.0, if you declare a variable before using it in your if, when, or while condition, then any information collected by the compiler about the variable will be accessible in the condition statement and its block for smart-casting.

This can be useful when you want to do things like extract boolean conditions into variables. Then, you can give the variable a meaningful name, which will improve your code readability and make it possible to reuse the variable later in your code. For example:

class Cat {
    fun purr() {
        println("Purr purr")
    }
}

fun petAnimal(animal: Any) {
    val isCat = animal is Cat
    if (isCat) {
        // In Kotlin 2.0.0, the compiler can access
        // information about isCat, so it knows that
        // animal was smart-cast to the type Cat.
        // Therefore, the purr() function is successfully called.
        // In Kotlin 1.9.20, the compiler doesn't know
        // about the smart cast, so calling the purr()
        // function triggers an error.
        animal.purr()
    }
}

fun main(){
    val kitty = Cat()
    petAnimal(kitty)
    // Purr purr
}

Type checks with the logical or operator

In Kotlin 2.0.0, if you combine type checks for objects with an or operator (||), a smart cast is made to their closest common supertype. Before this change, a smart cast was always made to the Any type.

In this case, you still had to manually check the object type afterward before you could access any of its properties or call its functions. For example:

interface Status {
    fun signal() {}
}

interface Ok : Status
interface Postponed : Status
interface Declined : Status

fun signalCheck(signalStatus: Any) {
    if (signalStatus is Postponed || signalStatus is Declined) {
        // signalStatus is smart-cast to a common supertype Status
        signalStatus.signal()
        // Prior to Kotlin 2.0.0-RC3, signalStatus is smart cast 
        // to type Any, so calling the signal() function triggered an
        // Unresolved reference error. The signal() function can only 
        // be called successfully after another type check:

        // check(signalStatus is Status)
        // signalStatus.signal()
    }
}

The common supertype is an approximation of a union type. Union types are not currently supported in Kotlin.

Inline functions

In Kotlin 2.0.0, the K2 compiler treats inline functions differently, allowing it to determine in combination with other compiler analyses whether it's safe to smart-cast.

Specifically, inline functions are now treated as having an implicit callsInPlace contract. This means that any lambda functions passed to an inline function are called in place. Since lambda functions are called in place, the compiler knows that a lambda function can't leak references to any variables contained within its function body.

The compiler uses this knowledge along with other compiler analyses to decide whether it's safe to smart-cast any of the captured variables. For example:

interface Processor {
    fun process()
}

inline fun inlineAction(f: () -> Unit) = f()

fun nextProcessor(): Processor? = null

fun runProcessor(): Processor? {
    var processor: Processor? = null
    inlineAction {
        // In Kotlin 2.0.0, the compiler knows that processor 
        // is a local variable and inlineAction() is an inline function, so 
        // references to processor can't be leaked. Therefore, it's safe 
        // to smart-cast processor.

        // If processor isn't null, processor is smart-cast
        if (processor != null) {
            // The compiler knows that processor isn't null, so no safe call 
            // is needed
            processor.process()

            // In Kotlin 1.9.20, you have to perform a safe call:
            // processor?.process()
        }

        processor = nextProcessor()
    }

    return processor
}

Properties with function types

In previous versions of Kotlin, there was a bug that meant that class properties with a function type weren't smart-cast. We fixed this behavior in Kotlin 2.0.0 and the K2 compiler. For example:

class Holder(val provider: (() -> Unit)?) {
    fun process() {
        // In Kotlin 2.0.0, if provider isn't null,
        // it is smart-cast
        if (provider != null) {
            // The compiler knows that provider isn't null
            provider()

            // In 1.9.20, the compiler doesn't know that provider isn't 
            // null, so it triggers an error:
            // Reference has a nullable type '(() -> Unit)?', use explicit '?.invoke()' to make a function-like call instead
        }
    }
}

This change also applies if you overload your invoke operator. For example:

interface Provider {
    operator fun invoke()
}

interface Processor : () -> String

class Holder(val provider: Provider?, val processor: Processor?) {
    fun process() {
        if (provider != null) {
            provider() 
            // In 1.9.20, the compiler triggers an error: 
            // Reference has a nullable type 'Provider?', use explicit '?.invoke()' to make a function-like call instead
        }
    }
}

Exception handling

In Kotlin 2.0.0, we've made improvements to exception handling so that smart cast information can be passed on to catch and finally blocks. This change makes your code safer as the compiler keeps track of whether your object has a nullable type. For example:

//sampleStart
fun testString() {
    var stringInput: String? = null
    // stringInput is smart-cast to String type
    stringInput = ""
    try {
        // The compiler knows that stringInput isn't null
        println(stringInput.length)
        // 0

        // The compiler rejects previous smart cast information for 
        // stringInput. Now stringInput has the String? type.
        stringInput = null

        // Trigger an exception
        if (2 > 1) throw Exception()
        stringInput = ""
    } catch (exception: Exception) {
        // In Kotlin 2.0.0, the compiler knows stringInput 
        // can be null, so stringInput stays nullable.
        println(stringInput?.length)
        // null

        // In Kotlin 1.9.20, the compiler says that a safe call isn't
        // needed, but this is incorrect.
    }
}
//sampleEnd
fun main() {
    testString()
}

Increment and decrement operators

Prior to Kotlin 2.0.0, the compiler didn't understand that the type of an object can change after using an increment or decrement operator. As the compiler couldn't accurately track the object type, your code could lead to unresolved reference errors. In Kotlin 2.0.0, this has been fixed:

interface Rho {
    operator fun inc(): Sigma = TODO()
}

interface Sigma : Rho {
    fun sigma() = Unit
}

interface Tau {
    fun tau() = Unit
}

fun main(input: Rho) {
    var unknownObject: Rho = input

    // Check if unknownObject inherits from the Tau interface
    if (unknownObject is Tau) {

        // Use the overloaded inc() operator from interface Rho,
        // which smart-casts the type of unknownObject to Sigma.
        ++unknownObject

        // In Kotlin 2.0.0, the compiler knows unknownObject has type
        // Sigma, so the sigma() function is called successfully.
        unknownObject.sigma()

        // In Kotlin 1.9.20, the compiler thinks unknownObject has type
        // Tau, so calling the sigma() function throws an error.

        // In Kotlin 2.0.0, the compiler knows unknownObject has type
        // Sigma, so calling the tau() function throws an error.
        unknownObject.tau()
        // Unresolved reference 'tau'

        // In Kotlin 1.9.20, the compiler mistakenly thinks that 
        // unknownObject has type Tau, so the tau() function is
        // called successfully.
    }
}

Kotlin Multiplatform

There are improvements in the K2 compiler related to Kotlin Multiplatform in the following areas:

• Separation of common and platform sources during compilation
• Different visibility levels of expected and actual declarations

Separation of common and platform sources during compilation

Previously, the design of the Kotlin compiler prevented it from keeping common and platform source sets separate at compile time. As a consequence, common code could access platform code, which resulted in different behavior between platforms. In addition, some compiler settings and dependencies from common code used to leak into platform code.

In Kotlin 2.0.0, our implementation of the new Kotlin K2 compiler included a redesign of the compilation scheme to ensure strict separation between common and platform source sets. This change is most noticeable when you use expected and actual functions. Previously, it was possible for a function call in your common code to resolve to a function in platform code. For example:

In this example, the common code has different behavior depending on which platform it is run on:

• On the JVM platform, calling the foo() function in the common code results in the foo() function from the platform code being called as platform foo.
• On the JavaScript platform, calling the foo() function in the common code results in the foo() function from the common code being called as common foo, as there is no such function available in the platform code.

In Kotlin 2.0.0, common code doesn't have access to platform code, so both platforms successfully resolve the foo() function to the foo() function in the common code: common foo.

In addition to the improved consistency of behavior across platforms, we also worked hard to fix cases where there was conflicting behavior between IntelliJ IDEA or Android Studio and the compiler. For instance, when you used expected and actual classes, the following would happen:

In this example, the expected class Identity has no default constructor, so it can't be called successfully in common code. Previously, an error was only reported by the IDE, but the code still compiled successfully on the JVM. However, now the compiler correctly reports an error:

Expected class 'expect class Identity : Any' does not have default constructor

When resolution behavior doesn't change

We're still in the process of migrating to the new compilation scheme, so the resolution behavior is still the same when you call functions that aren't within the same source set. You'll notice this difference mainly when you use overloads from a multiplatform library in your common code.

Suppose you have a library, which has two whichFun() functions with different signatures:

// Example library

// MODULE: common
fun whichFun(x: Any) = println("common function") 

// MODULE: JVM
fun whichFun(x: Int) = println("platform function")

If you call the whichFun() function in your common code, the function that has the most relevant argument type in the library will be resolved:

// A project that uses the example library for the JVM target

// MODULE: common
fun main(){
    whichFun(2) 
    // platform function
}

In comparison, if you declare the overloads for whichFun() within the same source set, the function from the common code will be resolved because your code doesn't have access to the platform-specific version:

// Example library isn't used

// MODULE: common
fun whichFun(x: Any) = println("common function") 

fun main(){
    whichFun(2) 
    // common function
}

// MODULE: JVM
fun whichFun(x: Int) = println("platform function")

Similar to multiplatform libraries, since the commonTest module is in a separate source set, it also still has access to platform-specific code. Therefore, the resolution of calls to functions in the commonTest module exhibits the same behavior as in the old compilation scheme.

In the future, these remaining cases will be more consistent with the new compilation scheme.

Different visibility levels of expected and actual declarations

Before Kotlin 2.0.0, if you used expected and actual declarations in your Kotlin Multiplatform project, they had to have the same visibility level. Kotlin 2.0.0 supports different visibility levels only if the actual declaration is less strict than the expected declaration. For example:

expect internal class Attribute // Visibility is internal
actual class Attribute          // Visibility is public by default, which is less strict

If you are using a type alias in your actual declaration, the visibility of the type must be less strict. Any visibility modifiers for actual typealias are ignored. For example:

expect internal class Attribute                // Visibility is internal
internal actual typealias Attribute = Expanded // The internal visibility modifier is ignored
class Expanded                                 // Visibility is public by default, which is less strict

How to enable the Kotlin K2 compiler

Starting with Kotlin 2.0.0-RC3, the Kotlin K2 compiler is enabled by default.

To upgrade the Kotlin version, change it to 2.0.0-RC3 in your Gradle and Maven build scripts.

Use Kotlin build reports with Gradle

Kotlin build reports provide information about the time spent in different compilation phases for Kotlin compiler tasks, as well as which compiler and Kotlin version were used, and whether the compilation was incremental. These build reports are useful for assessing your build performance. They offer more insight into the Kotlin compilation pipeline than Gradle build scans do because they give you an overview of the performance of all Gradle tasks.

How to enable build reports

To enable build reports, declare where you'd like to save the build report output in your gradle.properties file:

kotlin.build.report.output=file

The following values and their combinations are available for the output:

For more information on what is possible with build reports, see Build reports.

Try the Kotlin K2 compiler in the Kotlin Playground

The Kotlin Playground supports the 2.0.0-RC3 release. Check it out!

Support in IntelliJ IDEA

IntelliJ IDEA can use the new K2 compiler to analyze your code with its K2 Kotlin mode from IntelliJ IDEA 2024.1.

K2 Kotlin mode is in Alpha. The performance and stability of code highlighting and code completion have been improved, but not all IDE features are supported yet.

How to roll back to the previous compiler

To use the previous compiler in Kotlin 2.0.0-RC3, either:

• In your build.gradle.kts file, set your language version to 1.9.

  OR

• Use the following compiler option: -language-version 1.9.

Changes

With the introduction of the new frontend, the Kotlin compiler has undergone several changes. Let's start by highlighting the most significant modifications affecting your code, explaining what has changed and detailing best practices going forward. If you'd like to learn more, we've organized these changes into subject areas to facilitate your further reading.

This section highlights the following modifications:

• Immediate initialization of open properties with backing fields
• Deprecated synthetic setters on a projected receiver
• Forbidden function calls with inaccessible types
• Consistent resolution order of Kotlin properties and Java fields with the same name
• Improved null safety for Java primitive arrays

Immediate initialization of open properties with backing fields

What's changed?

In Kotlin 2.0, all open properties with backing fields must be immediately initialized; otherwise, you'll get a compilation error. Previously, only open var properties needed to be initialized right away, but now this extends to open val properties with backing fields too:

open class Base {
    open val a: Int
    open var b: Int

    init {
        // Error starting with Kotlin 2.0 that earlier compiled successfully 
        this.a = 1 //Error: open val must have initializer
        // Always an error
        this.b = 1 // Error: open var must have initializer
    }
}

class Derived : Base() {
    override val a: Int = 2
    override var b = 2
}

This change makes the compiler's behavior more predictable. Consider an example where an open val property is overridden by a var property with a custom setter.

If a custom setter is used, deferred initialization can lead to confusion because it's unclear whether you want to initialize the backing field or to invoke the setter. In the past, if you wanted to invoke the setter, the old compiler couldn't guarantee that the setter would then initialize the backing field.

What's the best practice now?

We encourage you to always initialize open properties with backing fields, as we believe this practice is both more efficient and less error-prone.

However, if you don't want to immediately initialize a property, you can:

• Make the property final.
• Use a private backing property that allows for deferred initialization.

Deprecated synthetics setter on a projected receiver

What's changed?

If you use the synthetic setter of a Java class to assign a type that conflicts with the class's projected type, an error is triggered.

Suppose you have a Java class named Container that contains the getFoo() and setFoo() methods:

public class Container<E> {
    public E getFoo() {
        return null;
    }
    public void setFoo(E foo) {}
}

If you have the following Kotlin code, where instances of the Container class have projected types, using the setFoo() method will always generate an error. However, only from Kotlin 2.0.0 will the synthetic foo property trigger an error:

fun exampleFunction(starProjected: Container<*>, inProjected: Container<in Number>, sampleString: String) {
    starProjected.setFoo(sampleString)
    // Error since Kotlin 1.0

    // Synthetic setter `foo` is resolved to the `setFoo()` method
    starProjected.foo = sampleString
    // Error since Kotlin 2.0.0

    inProjected.setFoo(sampleString)
    // Error since Kotlin 1.0

    // Synthetic setter `foo` is resolved to the `setFoo()` method
    inProjected.foo = sampleString
    // Error since Kotlin 2.0.0
}

What's the best practice now?

If you see that this change introduces errors in your code, you might wish to reconsider how you structure your type declarations. It could be that you don't need to use type projections, or perhaps you need to remove any assignments from your code.

For more information, see the corresponding issue in YouTrack.

Forbidden function calls with inaccessible types

What's changed?

Before Kotlin 2.0.0, if you declared or called a function that had lambda parameters with an inaccessible type, your code could compile, but you might encounter compiler crashes later. In Kotlin 2.0.0, it is forbidden to declare or call a function that has an inaccessible type.

For example, let's say that you declared a class in one module:

// Module one
class Some(val x: Int)

If you have another module (module two) that has a dependency configured on module one, your code can access the Some class and use it as a type in lambda expressions:

// Module two
fun foo(f: (Some, String) -> Unit) {}
fun bar(f: (Some) -> Unit) {}
// Both functions compile successfully

However, if you have a third module (module three) that depends only on module two, the third module won't be able to access the Some class in module one. As a result, the dependency won't be transitive between modules. Now, any functions in module three that have lambda parameters with the Some type will trigger errors in Kotlin 2.0.0, thus preventing crashes later in your code:

// Module three
fun test() {
    // Triggers an error in Kotlin 2.0.0, as the unused lambda
    // parameters (_) resolve to Some, which is inaccessible
    foo { _, _ -> }

    // Triggers a warning in Kotlin 2.0.0, as using an instance of Some
    // isn't possible because Some is inaccessible
    foo { some, str -> }
}

Errors are also introduced in Kotlin 2.0.0 for some scenarios involving generic classes. Consider, for example, the same arrangement of three modules but with generic classes:

In the third module, if you use the gen() function from module two to create an instance of the Generic class with the type Some<String> and then assign it to a variable z, this operation is successful because the gen() function has access to the Some<T> class in module one. However, if you try to pass the variable z to a function declared in module three, an error is triggered because functions declared in module three don't have access to the Some<T> class in module one:

// Module three
fun test() {
    // Triggers a warning in Kotlin 2.0.0
    val z = gen()

    // Triggers an error in Kotlin 2.0.0
    takeString(z)
}

What's the best practice now?

To avoid these problems, you can configure a direct dependency for module three on module one.

Alternatively, you can adapt your code to make the types accessible within the same module.

For more information, see the corresponding issue in YouTrack.

Consistent resolution order of Kotlin properties and Java fields with the same name

What's changed?

Before Kotlin 2.0.0, if you worked with Java and Kotlin classes that inherited from each other and contained Kotlin properties and Java fields with the same name, the resolution behavior of the duplicated name was inconsistent. There was also conflicting behavior between IntelliJ IDEA and the compiler. When developing the new resolution behavior for Kotlin 2.0.0, we aimed to cause the least impact to users.

For example, suppose there is a Java class Base:

public class Base {
    public String a = "a";

    public String b = "b";
}

Let's say there is also a Kotlin class Derived that inherits from the aforementioned Base class:

class Derived : Base() {
    val a = "aa"

    // Declares custom get() function
    val b get() = "bb"
}

fun main() {
    // Resolves Derived.a
    println(a)
    // aa

    // Resolves Base.b
    println(b)
    // b
}

Prior to Kotlin 2.0.0, a resolves to the Kotlin property within the Derived Kotlin class, whereas b resolves to the Java field in the Base Java class.

In Kotlin 2.0.0, the resolution behavior in the example is consistent, ensuring that the Kotlin property supersedes the Java field of the same name. Now, b resolves to: Derived.b.

Prior to Kotlin 2.0.0, if you used IntelliJ IDEA to go to the declaration or usage of a, it would incorrectly navigate to the Java field when it should have navigated to the Kotlin property.

From Kotlin 2.0.0, IntelliJ IDEA correctly navigates to the same location as the compiler.

{type ="note"}

The general rule is that the subclass takes precedence. The previous example demonstrates this, as the Kotlin property a from the Derived class is resolved because Derived is a subclass of the Base Java class.

In the event that the inheritance is reversed and a Java class inherits from a Kotlin class, the Java field in the subclass takes precedence over the Kotlin property with the same name.

Consider this example:

Now in the following code:

fun main() {
    // Resolves Derived.a
    println(a)
    // a
}

What's the best practice now?

If this change affects your code, consider whether you really need to use duplicate names. If you want to have Java or Kotlin classes that each contain a field or property with the same name and that each inherit from one another, keep in mind that the field or property in the subclass will take precedence.

For more information, see the corresponding issue in YouTrack.

Improved null safety for Java primitive arrays

What's changed?

Starting with Kotlin 2.0.0, the compiler correctly infers the nullability of Java primitive arrays imported to Kotlin. Now, it retains native nullability from the TYPE_USE annotations used with Java primitive arrays and emits errors when their values are not used according to annotations.

Usually, when Java types with @Nullable and @NotNull annotations are called from Kotlin, they receive the appropriate native nullability:

interface DataService {
    @NotNull ResultContainer<@Nullable String> fetchData();
}

val dataService: DataService = ... 
dataService.fetchData() // -> ResultContainer<String?>

Previously, however, when Java primitive arrays were imported to Kotlin, all TYPE_USE annotations were lost, resulting in platform nullability and possibly unsafe code:

interface DataProvider {
    int @Nullable [] fetchData();
}

val dataService: DataProvider = ...
dataService.fetchData() // -> IntArray .. IntArray?
// No error, even though `dataService.fetchData()` might be `null` according to annotations
// This might result in a NullPointerException
dataService.fetchData()[0]

Note that this issue never affected nullability annotations on the declaration itself, only the TYPE_USE ones.

What's the best practice now?

In Kotlin 2.0.0, null safety for Java primitive arrays is now standard in Kotlin, so check your code for new warnings and errors if you use them:

• Any code that uses a @Nullable Java primitive array without an explicit nullability check or attempts to pass null to a Java method expecting a non-nullable primitive array will now fail to compile.
• Using a @NotNull primitive array with a nullability check now emits "Unnecessary safe call" or "Comparison with null always false" warnings.

For more information, see the corresponding issue in YouTrack.

Per subject area

These subject areas list changes that are unlikely to affect your code but provide links to the relevant YouTrack issues for further reading. Changes listed with an asterisk (*) next to the Issue ID are explained at the beginning of the section.

Type inference

Generics

Resolution

Visibility

Annotations

Null safety

Java interoperability

Properties

Control flow

Enum classes

Functional (SAM) interfaces

Companion object

Miscellaneous

Compatibility with Kotlin releases

The following Kotlin releases have support for the new K2 compiler:

Compiler plugins support

Currently, the Kotlin K2 compiler supports the following Kotlin compiler plugins:

• all-open
• AtomicFU
• jvm-abi-gen
• js-plain-objects
• kapt
• Lombok
• no-arg
• Parcelize
• SAM with receiver
• Serialization

In addition, the Kotlin K2 compiler supports:

• The Jetpack Compose 1.5.0 compiler plugin and later versions.
• The Kotlin Symbol Processing (KSP) plugin since KSP2.

If you use any additional compiler plugins, check their documentation to see if they are compatible with K2.

Share your feedback on the new K2 compiler

We would appreciate any feedback you may have!

• Provide your feedback directly to K2 developers in the Kotlin Slack workspace – get an invite and join the #k2-early-adopters channel.
• Report any problems you face migrating to the new K2 compiler in our issue tracker.
• Enable the Send usage statistics option to allow JetBrains to collect anonymous data about K2 usage.