Kotlin Multiplatform, from the compiler up · Puzzle 1 · 2 of 10

What every target has

In puzzle 0, one Kotlin file became bytecode and native code. But some code only makes sense on one platform. Here's how a project says which code goes where.

The problem

In puzzle 0, one Kotlin file was compiled for Android and for an iPhone. Now your shared code reads a file with java.io.File. On Android, fine: it's part of the Java library the JVM brings. An iPhone has no Java library at all. Which code is allowed to call what, and who decides?

See it

Three folders: commonMain goes to both phones; androidMain only to Android; iosMain only to the iPhone; a Java class in commonMain fails for the iPhone Android iPhone commonMainLogin rules androidMainiosMain java.io.File UIDevice
  1. Code lives in source sets. commonMain holds the common code and is compiled for every target, Android and iPhone alike.

    Step 1 of 4
  2. androidMain is compiled only for Android; iosMain only for iOS. Each can use its own platform's APIs.

    Step 2 of 4
  3. Common code calls java.io.File. Fine for Android, but the iPhone has no Java library: the iOS build fails. Predict: where does iPhone-only code go?

    Step 3 of 4
  4. Into iosMain, where Apple's APIs, like UIDevice, are allowed: it's only ever compiled for iOS.

    Step 4 of 4

The building block

A multiplatform project keeps its code in source sets: folders, each compiled for a chosen set of targets.

commonMain is compiled for every target. Its code is the common code, and it may only use what every target has: the Kotlin standard library, and libraries built for every target themselves, like Kotlin's own coroutines library. java.io.File isn't one of them, because the iPhone has no Java library to provide it.

androidMain is compiled only for Android, so it can use anything Android and Java offer. iosMain is compiled only for iOS, so it can use Apple's own APIs, like UIDevice. Common code can't see into either: it doesn't know which platform it will end up on.

In Gradle, you list the targets in the build file, and each source set is a folder under src, like src/commonMain and src/iosMain.

The rule is what makes sharing safe: if something compiles in commonMain, it has something to run on, on every target.

The analogy

A company with offices in two countries. Rules in the shared handbook must make sense in both, so they can't say "call the local tax office by its name". Each office keeps a local folder for what only applies there.

Check yourself

You call java.io.File in commonMain, and the project has Android and iOS targets. What happens when you build for iOS?

Not quite. Common code is compiled for every target; on iOS it can't compile at all.

Not quite. Kotlin/Native compiles your Kotlin; it can't bring along a Java library the iPhone doesn't have.

Right. Common code may only use what every target has.

Why can't common code call Android's own APIs?

Not quite. The language isn't the problem: those APIs don't exist on the iPhone. Re-read that part ↑

Right. What every target has is the limit.

What's the difference between commonMain and iosMain?

Not quite. The split is about which targets the code is compiled for, not about logic versus screens.

Right. Which targets a source set is compiled for.

Not quite. Both are Kotlin; they're compiled for different targets.

Sources

  • Kotlin docs: The basics of Kotlin Multiplatform project structure ("Common code is the Kotlin code shared among different platforms… 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"; "a shared module with the commonMain, iosMain, and androidMain source sets")

What you now know

Code lives in source sets. commonMain is compiled for every target, so it may only use what every target has; androidMain and iosMain are compiled for one platform each and can use that platform's own APIs.