Compatibility guide for Kotlin Multiplatform

What's changed?

The access to KotlinCompilation.source has been deprecated. A code like this produces a deprecation warning:

kotlin {
    jvm()
    js()
    iosArm64()
    iosSimulatorArm64()

    sourceSets {
        val commonMain by getting
        val myCustomIntermediateSourceSet by creating {
            dependsOn(commonMain)
        }

        targets["jvm"].compilations["main"].source(myCustomIntermediateSourceSet)
    }
}

What's the best practice now?

To replace KotlinCompilation.source(someSourceSet), add the dependsOn relation from the default source set of the KotlinCompilation to someSourceSet. We recommend referring to the source directly using by getting, which is shorter and more readable. However, you can also use KotlinCompilation.defaultSourceSet.dependsOn(someSourceSet), which is applicable in all cases.

You can change the code above in one of the following ways:

kotlin {
    jvm()
    js()
    iosArm64()
    iosSimulatorArm64()

    sourceSets {
        val commonMain by getting
        val myCustomIntermediateSourceSet by creating {
            dependsOn(commonMain)
        }

        // Option #1. Shorter and more readable, use it when possible.
        // Usually, the name of the default source set
        // is a simple concatenation of the target name and the compilation name:
        val jvmMain by getting {
            dependsOn(myCustomIntermediateSourceSet)
        }

        // Option #2. Generic solution, use it if your build script requires a more advanced approach:
        targets["jvm"].compilations["main"].defaultSourceSet.dependsOn(myCustomIntermediateSourceSet)
    }
}

When do the changes take effect?

Here's the planned deprecation cycle:

• 1.9.0: introduce a deprecation warning when KotlinComplation.source is used

• 1.9.20: raise this warning to an error

• >1.9.20: remove KotlinComplation.source from the Kotlin Gradle plugin, attempts to use it lead to "unresolved reference" errors during the buildscript compilation

What's changed?

Starting with Kotlin 1.9.0, the kotlin-js Gradle plugin is deprecated. Basically, it duplicated the functionality of the kotlin-multiplatform plugin with the js() target and shared the same implementation under the hood. Such overlap created confusion and increased maintenance load on the Kotlin team. We encourage you to migrate to the kotlin-multiplatform Gradle plugin with the js() target instead.

What's the best practice now?

1. Remove the kotlin-js Gradle plugin from your project and apply kotlin-multiplatform in the settings.gradle.kts file if you're using the pluginManagement {} block:

   kotlin-js

   kotlin-multiplatform

   // settings.gradle.kts:
   pluginManagement {
       plugins {
           // Remove the following line:
           kotlin("js") version "1.9.0"
       }
   
       repositories {
           // ...
       }
   }

   // settings.gradle.kts:
   pluginManagement {
       plugins {
           // Add the following line instead:
           kotlin("multiplatform") version "1.9.0"
       }
   
       repositories {
           // ...
       }
   }

   In case you're using a different way of applying plugins, see the Gradle documentation for migration instructions.

2. Move your source files from the main and test folders to the jsMain and jsTest folders in the same directory.

3. Adjust dependency declarations:

   • We recommend using the sourceSets {} block and configuring dependencies of respective source sets, jsMain {} for production dependencies and jsTest {} for test dependencies. See Adding dependencies for more details.

   • However, if you want to declare your dependencies in a top-level block, change declarations from api("group:artifact:1.0") to add("jsMainApi", "group:artifact:1.0") and so on.

     note

     In this case, make sure that the top-level dependencies {} block comes after the kotlin {} block. Otherwise, you'll get an error "Configuration not found".

   You can change the code in your build.gradle.kts file in one of the following ways:

   kotlin-js

   kotlin-multiplatform

   // build.gradle.kts:
   plugins {
       kotlin("js") version "1.9.0"
   }
   
   dependencies {
       testImplementation(kotlin("test"))
       implementation("org.jetbrains.kotlinx:kotlinx-html:0.8.0")
   }
   
   kotlin {
       js {
           // ...
       }
   }

   // build.gradle.kts:
   plugins {
       kotlin("multiplatform") version "1.9.0"
   }
   
   kotlin {
       js {
           // ...
       }
   
       // Option #1. Declare dependencies in the sourceSets {} block:
       sourceSets {
           val jsMain by getting {
               dependencies {
                   // No need for the js prefix here, you can just copy and paste it from the top-level block
                   implementation("org.jetbrains.kotlinx:kotlinx-html:0.8.0")
               }
          }
       }
   }
   
   dependencies {
       // Option #2. Add the js prefix to the dependency declaration:
       add("jsTestImplementation", kotlin("test"))
   }

4. The DSL provided by the Kotlin Gradle plugin inside the kotlin {} block remains unchanged in most cases. However, if you were referring to low-level Gradle entities, like tasks and configurations, by names, you now need to adjust them, usually by adding the js prefix. For example, you can find the browserTest task under the name jsBrowserTest.

When do the changes take effect?

In 1.9.0, the use of the kotlin-js Gradle plugin produces a deprecation warning.

What's changed?

targetPresets.jvmWithJava is deprecated, and its usage is discouraged.

What's the best practice now?

Use jvm { withJava() } target instead. Note that after switching to jvm { withJava() }, you'll need to adjust the paths to source directories with .java sources.

For example, if you use a jvm target with the default name "jvm":

When do the changes take effect?

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

• tip

  1.9.20: remove targetPresets.jvmWithJava API; attempts to use it lead to the buildscript compilation failure

note

Even though the whole targetPresets API is deprecated, the jvmWithJava preset has a different deprecation timeline.

What's changed?

The new Android source set layout is used by default since Kotlin 1.9.0. Support for the legacy layout is deprecated, and the use of the kotlin.mpp.androidSourceSetLayoutVersion Gradle property now triggers a deprecation diagnostic.

When do the changes take effect?

Here's the planned deprecation cycle:

• <=1.9.0: report a warning when kotlin.mpp.androidSourceSetLayoutVersion=1 is used; the warning can be suppressed with kotlin.mpp.androidSourceSetLayoutVersion1.nowarn=true Gradle property

• 1.9.20: raise this warning to an error; the error cannot be suppressed

• >1.9.20: remove support for kotlin.mpp.androidSourceSetLayoutVersion=1; the Kotlin Gradle plugin ignores the property

What's changed?

The commonMain and commonTest source sets usually represent the roots of the main and test source set hierarchies, respectively. However, it was possible to override that by manually configuring dependsOn relations of these source sets.

Maintaining such configuration requires extra effort and knowledge about multiplatform build internals. Additionally, it decreases code readability and reusability of the code because you need to read the particular buildscript to be sure whether commonMain is the root of the main source set hierarchy.

Therefore, accessing dependsOn on commonMain and commonTest is now deprecated.

What's the best practice now?

Suppose you need to migrate to 1.9.20 the customCommonMain source set that uses commonMain.dependsOn(customCommonMain). In most cases, customCommonMain participates in the same compilations as commonMain, so you can merge customCommonMain into commonMain:

1. Copy sources of customCommonMain into commonMain.

2. Add all dependencies of customCommonMain to commonMain.

3. Add all compiler option settings of customCommonMain to commonMain.

In rare cases, customCommonMain might be participating in more compilations than commonMain. Such a configuration requires additional low-level configuration of the build script. If you're not sure if that's your use case, it most likely isn't.

If it is your use case, "swap" these two source sets by moving the sources and settings of customCommonMain to commonMain and vice versa.

When do the changes take effect?

Here's the planned deprecation cycle:

• 1.9.0: report a warning when dependsOn is used in commonMain

• >=1.9.20: report an error when dependsOn is used in commonMain or commonTest

What's changed?

The JetBrains team has revamped the approach to forward declarations in Kotlin to make their behavior more predictable:

• You can only import forward declarations using the cnames or objcnames packages.

• You need to explicitly make a cast to and from the corresponding C and Objective-C forward declaration.

What's the best practice now?

• Consider a C library with a library.package that declares a cstructName forward declaration. Previously, it was possible to import it directly from the library with import library.package.cstructName. Now, you can only use a special forward declaration package for that: import cnames.structs.cstructName. The same is true for objcnames.

• Consider two objcinterop libraries: one that uses objcnames.protocols.ForwardDeclaredProtocolProtocol and another that has an actual definition:

  // First objcinterop library
  #import <Foundation/Foundation.h>
  
  @protocol ForwardDeclaredProtocol;
  
  NSString* consumeProtocol(id<ForwardDeclaredProtocol> s) {
      return [NSString stringWithUTF8String:"Protocol"];
  }

  // Second objcinterop library
  // Header:
  #import <Foundation/Foundation.h>
  @protocol ForwardDeclaredProtocol
  @end
  // Implementation:
  @interface ForwardDeclaredProtocolImpl : NSObject <ForwardDeclaredProtocol>
  @end
  
  id<ForwardDeclaredProtocol> produceProtocol() {
      return [ForwardDeclaredProtocolImpl new];
  }

  Previously, it was possible to transfer objects between them seamlessly. Now, an explicit as cast is required for the forward declaration:

  // Kotlin code:
  fun test() {
      consumeProtocol(produceProtocol() as objcnames.protocols.ForwardDeclaredProtocolProtocol)
  }

  note

  You can only cast to objcnames.protocols.ForwardDeclaredProtocolProtocol from the corresponding real class. Otherwise, you'll get an error.

When do the changes take effect?

Starting with Kotlin 1.9.20, you need to explicitly make a cast to and from the corresponding C and Objective-C forward declarations. Also, it's now only possible to import forward declarations by using special packages.

What's changed?

Due to compatibility issues between the Kotlin Multiplatform Gradle plugin and the Gradle plugins Java, Java Library, and Application, there is now a deprecation warning when you apply these plugins to the same project. The warning also appears when another Gradle plugin in your multiplatform project applies a Gradle Java plugin. For example, the Spring Boot Gradle Plugin automatically applies the Application plugin. In future Kotlin releases, the warning will be increased to an error.

We've added this deprecation warning due to fundamental compatibility issues between Kotlin Multiplatform's project model and Gradle's Java ecosystem plugins. Gradle's Java ecosystem plugins currently don't take into account that other plugins may:

• Also publish or compile for the JVM target in a different way than the Java ecosystem plugins.

• Have two different JVM targets in the same project, such as JVM and Android.

• Have a complex multiplatform project structure with potentially multiple non-JVM targets.

Unfortunately, Gradle doesn't currently provide any API to address these issues.

We previously used some workarounds in Kotlin Multiplatform to help with the integration of Java ecosystem plugins. However, these workarounds never truly solved the compatibility issues, and since the release of Gradle 8.8, these workarounds are no longer possible. For more information, see our YouTrack issue.

While we don't yet know exactly how to resolve this compatibility problem, we are committed to continuing support for some form of Java source compilation in your Kotlin Multiplatform projects. At a minimum, we will support the compilation of Java sources and using Gradle's java-base plugin within your multiplatform projects.

What's the best practice now?

If you see this deprecation warning in your multiplatform project, we recommend that you:

1. Determine whether you actually need the Gradle Java plugin in your project. If not, consider removing it.

2. Check if the Gradle Java plugin is only used for a single task. If so, you might be able to remove the plugin without much effort. For example, if the task uses a Gradle Java plugin to create a Javadoc JAR file, you can define the Javadoc task manually instead.

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 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.

warning

The separate subproject must not be a multiplatform project, and you must only use it to set up a dependency on your multiplatform project.

For example, you have a multiplatform project called my-main-project and you want to use the Java Library Gradle plugin.

Once you've created a subproject, let's call it subproject-A, your parent project structure should look like this:

.
├── build.gradle
├── settings.gradle.kts
├── subproject-A
    └── build.gradle.kts
    └── src
        └── Main.java

In your subproject's build.gradle.kts file, apply the Java Library plugin in the plugins {} block:

plugins {
    id("java-library")
}

plugins {
    id('java-library')
}

In your subproject's build.gradle.kts file, add a dependency on your parent multiplatform project:

dependencies {
    implementation(project(":my-main-project")) // The name of your parent multiplatform project
}

dependencies {
    implementation project(':my-main-project') // The name of your parent multiplatform project
}

Your parent project is now set up to work with both plugins.

What's changed?

Target accessors auto-generated by Gradle are no longer available inside the kotlin.targets {} block. Use the findByName("targetName") method instead.

Note that such accessors are still available in the kotlin.targets {} case, for example, kotlin.targets.linuxX64.

What's the best practice now?

kotlin {
    targets {
        configure(['windows',
            'linux']) {
        }
    }
}

kotlin {
    targets {
        configure([findByName('windows'),
            findByName('linux')]) {
        }
    }
}

When do the changes take effect?

In Kotlin 1.7.20, an error is introduced when using target accessors in the kotlin.targets {} block.

For more information, see the corresponding issue in YouTrack.

What's changed?

Kotlin compile tasks no longer inherit the Gradle AbstractCompile task that has the sourceCompatibility and targetCompatibility inputs, making them unavailable in Kotlin users' scripts.

Other breaking changes in compile tasks:

What's the best practice now?

When do the changes take effect?

In Kotlin 1.7.20, inputs are not available, the output is replaced, and the classpath property is deprecated.

For more information, see the corresponding issue in YouTrack.

What's changed?

Compilation configurations created by the Kotlin Multiplatform Gradle Plugin received new names.

A target in the Kotlin Multiplatform project has two default compilations, main and test. Each of these compilations has its own default source set, for example, jvmMain and jvmTest. Previously the configuration names for the test compilation and its default source set were the same, which might lead to a name clash resulting in issues when a configuration marked with platform-specific attributes is included in another configuration.

Now compilation configurations have an extra Compilation postfix, while projects and plugins that use old hard-coded configuration names no longer compile.

Configuration names for dependencies on the corresponding source set stay the same.

What's the best practice now?

jvm<Scope>

jvmCompilation<Scope>

dependencies {
    add("jvmImplementation",
        "foo.bar.baz:1.2.3")
}

dependencies {
    add("jvmCompilationImplementation",
        "foo.bar.baz:1.2.3")
}

jvmMain<Scope>

jvmTest<Scope>

jvmTestCompilation<Scope>

jvmTest<Scope>

The available scopes are Api, Implementation, CompileOnly, and RuntimeOnly.

When do the changes take effect?

In Kotlin 1.8.0, an error is introduced when using old configuration names in hard-coded strings.

For more information, see the corresponding issue in YouTrack.