The basics of Kotlin Multiplatform project structure | Kotlin Multiplatform Documentation
The basics of Kotlin Multiplatform project structure With Kotlin Multiplatform, you can share code among different platforms. This article explains the constraints of the shared code, how to distinguish between shared and platform-specific parts of your code, and how to specify the platforms on which this shared code works. You'll also learn the core concepts of Kotlin Multiplatform project setup, such as common code, targets, platform-specific and intermediate source sets, and test integration.
That will help you set up your multiplatform projects in the future. The model presented here is simplified compared to the one used by Kotlin. However, this basic model should be adequate for the majority of cases. Common code Common code is the Kotlin code shared among different platforms. Consider the simple "Hello, World" example: fun greeting() { println("Hello, Kotlin Multiplatform!") } Kotlin code shared among platforms is typically located in the commonMain directory.
The location of code files is important, as it affects the list of platforms to which this code is compiled. The Kotlin compiler gets the source code as input and produces a set of platform-specific binaries as a result. When compiling multiplatform projects, it can produce multiple binaries from the same code. For example, the compiler can produce JVM .class files and native executable files from the same Kotlin file: Not every piece of Kotlin code can be compiled to all platforms.
The Kotlin compiler prevents you from using platform-specific functions or classes in your common code if this code can't be compiled to a different platform. For instance, you can't use the java.io.File dependency from the common code. It's a part of the JDK, while common code is also compiled to native code, where the JDK classes are not available: In common code, you can use Kotlin Multiplatform libraries. These libraries provide a common API that can be implemented differently on different platforms.
In this case, platform-specific APIs serve as extra parts, and trying to use such an API in common code results in an error. For example, kotlinx.coroutines is a Kotlin Multiplatform library that supports all targets, but it also has a platform-specific part that converts kotlinx.coroutines concurrent primitives to JDK concurrent primitives, like fun CoroutinesDispatcher.asExecutor(): Executor . This additional part of the API isn't available in commonMain .
To explore available Kotlin Mutliplatform libraries, see klibs.io . Targets Targets define the platforms to which Kotlin compiles the common code. These could be, for example, the JVM, JS, Android, iOS, or Linux. The previous example compiled the common code to the JVM and native targets. A Kotlin target is an identifier that describes a compilation target. It defines the format of the produced binaries, available language constructions, and allowed dependencies.
You should first declare a target to instruct Kotlin to compile code for that specific target. In Gradle, you declare targets using predefined DSL calls inside the kotlin {} block: kotlin { jvm() // Declares a JVM target iosArm64() // Declares a target that corresponds to 64-bit iPhones } This way, each multiplatform project defines a set of supported targets. See the Hierarchical project structure section to learn more about declaring targets in your build scripts.
With the jvm and iosArm64 targets declared, the common code in commonMain will be compiled to these targets: To understand which code is going to be compiled to a specific target, you can think of a target as a label attached to Kotlin source files. Kotlin uses these labels to determine how to compile your code, which binaries to produce, and which language constructions and dependencies are allowed in that code. If you want to compile the greeting.kt file to .js as well, you only need to declare the JS target.
The code in commonMain then receives an additional js label, corresponding to the JS target, which instructs Kotlin to produce .js files: That's how the Kotlin compiler works with the common code compiled to all the declared targets. See Source sets to learn how to write platform-specific code. Source sets A Gradle source set is a set of source files with its own targets, dependencies, and compiler options. It's the main way to share code in multiplatform projects.
Each source set in a multiplatform project: Has a name that is unique for a given project. Contains a set of source files and resources, usually stored in the directory with the name of the source set. Specifies a set of targets to which the code in this source set compiles. These targets impact which language constructions and dependencies are available in this source set. Defines its own dependencies and the compiler options.
Kotlin Multiplatform provides a number of predefined source sets. One of them is commonMain , which is present in all multiplatform projects and compiles to all declared targets. You interact with source sets as directories inside src in Kotlin Multiplatform projects. For example, a shared module with the commonMain , iosMain , and androidMain source sets has the following structure: When the shared module is built into an Android library, common Kotlin code is treated as Kotlin/JVM.
When it's built into an iOS framework, common Kotlin is treated as Kotlin/Native: In Gradle scripts, you access source sets by name inside the kotlin.sourceSets {} block: kotlin { // Targets declaration: // … // Source set declaration: sourceSets { commonMain { // Configure the commonMain source set } } } Aside from commonMain , other source sets can be either platform-specific or intermediate. Platform-specific source sets While having only common code is convenient, it's not always possible.
Code in commonMain compiles to all declared targets, and Kotlin doesn't allow you to use any platform-specific APIs there. In a multiplatform project with native and JS targets, the following code in commonMain doesn't compile: // commonMain/kotlin/common.kt // Doesn't compile in common code fun greeting() { java.io.File("greeting.txt").writeText("Hello, Multiplatform!") } As a solution, Kotlin creates platform-specific source sets, also referred to as platform source sets.
Each target has a corresponding platform source set that compiles for only that target. For example, a jvm target has the corresponding jvmMain source set that compiles to only the JVM. Kotlin allows using platform-specific dependencies in these source sets, for instance, JDK in jvmMain : // jvmMain/kotlin/jvm.kt // You can use Java dependencies in the `jvmMain` source set fun jvmGreeting() { java.io.File("greeting.txt").writeText("Hello, Multiplatform!") } Compilation to a specific target Compilation to a specific target works with multiple source sets.
When Kotlin compiles a multiplatform project to a specific target, it collects all source sets labeled with this target and produces binaries from them. Consider an example with jvm , iosArm64 , and js targets. Kotlin creates the commonMain source set for common code and the corresponding jvmMain , iosArm64Main , and jsMain source sets for specific targets: During compilation to the JVM, Kotlin selects all source sets labeled with "JVM", namely, jvmMain and commonMain .
It then compiles them together to the JVM class files: Because Kotlin compiles commonMain and jvmMain together, the resulting binaries contain declarations from both commonMain and jvmMain . When working with multiplatform projects, remember: If you want Kotlin to compile your code to a specific platform, declare a corresponding target. To choose a directory or source file to store the code, first decide among which targets you want to share your code: If the code is shared among all targets, it should be declared in commonMain .
If the code is used for only one target, it should be defined in a platform-specific source set for that target (for example, jvmMain for the JVM). Code writt
The rest of this page is on the live site.