CoursesKotlin Multiplatform, from the compiler up

Puzzle 17 · 18 of 20

Source sets in between

In puzzle 16, every target got a source set of its own, and none of them was iosMain. Your iOS code is the same for a real iPhone and the simulator, and it shouldn't be written twice. Here's where iosMain really comes from.

All puzzles in this course

The problem

In puzzle 16, each target got its own platform source set: androidMain, iosArm64Main, iosSimulatorArm64Main. But the Kotlin you write for iOS is the same for a real iPhone and for the simulator. Put it in both iOS folders and every fix has to be made twice, the very problem this course started from in puzzle 0. And puzzle 1's iosMain wasn't in the list at all. Where does it come from?

See it

Three platform source sets under commonMain; iOS code written twice moves up into iosMain, shared by both iOS targets; the template adds appleMain and nativeMain above it but no watchosMain; building iosArm64 compiles every source set on its path up to commonMain commonMain androidMain iosArm64Main iosSimulatorArm64Main written twice iosMain nativeMainappleMainwatchosMain iosArm64MainiosMainappleMainnativeMain

Scroll sideways to see the full diagram.

  1. Puzzle 16's targets, each with its platform source set under commonMain. The iOS code is the same for both iOS targets, so it's written twice.

    Step 1 of 5
  2. An intermediate source set is compiled for some targets, not all. iosMain sits above both iOS targets: the code moves up and is written once.

    Step 2 of 5
  3. You didn't create iosMain: the plugin's default hierarchy template did, with appleMain and nativeMain above it. No watch target, so no watchosMain.

    Step 3 of 5
  4. Now build the iosArm64 target. Predict: which source sets are compiled into it?

    Step 4 of 5
  5. Every source set on its path up, in one compilation: iosArm64Main, iosMain, appleMain, nativeMain and commonMain. androidMain isn't on the path.

    Step 5 of 5

The building block

An intermediate source set is compiled for some of the project's targets, but not all. iosMain is one: it's compiled for both iOS targets, so code written there reaches a real iPhone and the simulator, and it's written once. That's where your iOS code goes. The platform source sets below it usually stay empty; Kotlin's docs call iosArm64Main "rarely used".

You don't create iosMain yourself. The multiplatform plugin carries a default hierarchy template: a built-in tree of intermediate source sets, from which it creates the ones that fit the targets you declared. For puzzle 16's three targets, that's this tree (each source set sits under the one it's compiled together with):

commonMain
├── androidMain
└── nativeMain
    └── appleMain
        └── iosMain
            ├── iosArm64Main
            └── iosSimulatorArm64Main

Each level covers a wider group of targets:

Source setCompiled for
iosMainevery iOS target: iPhones and the simulator
appleMainevery Apple target: iPhone, Mac, Apple Watch, Apple TV
nativeMainevery Kotlin/Native target: Apple's, but also Linux and Windows
commonMainevery target

A level only appears when you have a target for it. With no watch target, there's no watchosMain. Add one, such as watchosArm64, and the plugin creates watchosMain under appleMain, and the code in appleMain, nativeMain and commonMain is compiled for the watch too. The same tree exists for tests: commonTest, iosTest and so on.

The tree also tells you what each compilation from puzzle 16 takes in. To build a target, Kotlin collects every source set on that target's path up the tree. Building iosArm64 compiles iosArm64Main, iosMain, appleMain, nativeMain and commonMain together. androidMain isn't on that path, so it's never part of an iOS build.

The analogy

The company from puzzle 1 groups its offices. There's the shared handbook for everyone, a folder for every office in Asia, and a folder for Japan, where the company has two offices: Tokyo, and the training office at headquarters (the simulator). A rule for Japan goes into the Japan folder once, not into each office's own folder. When an office prints its handbook, it binds in every folder on its line: shared, Asia, Japan, then its own folder.

Check yourself

Your project declares the android, iosArm64 and iosSimulatorArm64 targets. You put a function in appleMain. Which builds compile it?

Right. Code reaches the targets below its source set.

Not quite. Code reaches only the targets below it; Android isn't under appleMain.

Not quite. appleMain is for every Apple target in the project; here those are the two iOS targets. Re-read that part ↑

Why put your iOS code in iosMain rather than in iosArm64Main?

Right. One place for every iOS target.

Not quite. A platform source set is compiled for exactly one target: here, iosArm64.

Not quite. It holds iosArm64's main code; tests go in the test source sets.

What's the difference between a platform source set and an intermediate source set?

Right. One target vs some.

Not quite. That's commonMain; an intermediate one covers some targets, not all.

Not quite. androidMain is a platform source set too; what differs is how many targets.

Sources
  • Kotlin docs: The basics of Kotlin Multiplatform project structure ("An intermediate source set is a Kotlin source set that compiles to some, but not all of the targets in the project"; "there is no single ios target"; "Platform-specific source sets like iosArm64Main and iosSimulatorArm64Main are usually empty, as Kotlin code for iOS devices and simulators is normally the same. You can use only the iosMain intermediate source set to share code among all of them"; "iosArm64Main is therefore rarely used"; "During compilation to a specific target, Kotlin gets all of the source sets, including intermediate source sets, labeled with this target")
  • Kotlin docs: Source set hierarchy ("The Kotlin Gradle plugin has a built-in default hierarchy template. It contains predefined intermediate source sets for some popular use cases. The plugin sets up those source sets automatically based on the targets specified in your project"; "If you add a watchOS target, like watchosArm64, the watchos source set is created, and the code from the apple, native, and common source sets is compiled to watchosArm64 as well"; "everything is the same for *Test sources as well")

What you now know

An intermediate source set is compiled for some, but not all, of a project's targets. The multiplatform plugin's default hierarchy template creates them for the targets you declare: iosMain above both iOS targets, appleMain above every Apple target, nativeMain above every Kotlin/Native target, all under commonMain. Building a target compiles every source set on its path up the tree.