CoursesKotlin Multiplatform, from the compiler up

Puzzle 16 · 17 of 20

The kotlin { } block

Puzzle 1 said, in passing, that you list the targets in the build file. You use Gradle every day, but a shared module's build file has a block you've never written. Here's what it declares, and why "Android and iOS" means three targets.

All puzzles in this course

The problem

Puzzle 1 put your code into source sets and said, in passing, that you list the targets in the build file. In an Android module you know that file by heart: plugins { }, android { }, dependencies { }. A shared module's build.gradle.kts has a block you've never written, and it lists three targets for an app that runs on "Android and iOS". What does that block declare, and where does each line lead?

See it

A shared module's build file lists three targets in its kotlin block: Android, iosArm64 for iPhones and iosSimulatorArm64 for the simulator on a Mac; each target gets its own source set, and each iOS target gets a main and a test compilation that join commonMain with that source set shared/build.gradle.ktskotlin {android { … }iosArm64()iosSimulatorArm64()} AndroidiPhoneMac androidMainiosArm64MainiosSimulatorArm64Main commonMainmaintestmaintest

Scroll sideways to see the full diagram.

  1. A shared module's build file has a kotlin { } block. The multiplatform plugin, a Gradle plugin like Android's, reads it.

    Step 1 of 4
  2. Each line declares a target. iOS takes two: iosArm64 for real iPhones, iosSimulatorArm64 for the simulator, the stand-in iPhone that runs on your Mac.

    Step 2 of 4
  3. Each target gets a platform source set of its own, named after it. Predict: when iosArm64 is built, which source sets go in?

    Step 3 of 4
  4. Its own and commonMain, joined in one compilation: one compiler run for one target. Each iOS target has two: main for your code, test for your tests.

    Step 4 of 4

The building block

The multiplatform plugin, kotlin("multiplatform"), is a Gradle plugin like the Android one you already apply. It reads the kotlin { } block, where each line declares one target:

// shared/build.gradle.kts
plugins {
    kotlin("multiplatform")
    id("com.android.kotlin.multiplatform.library")
}

kotlin {
    android {
        namespace = "com.example.shared"
        compileSdk = 36
        minSdk = 24
    }
    iosArm64()
    iosSimulatorArm64()
}

Android's line is a block because the Android target needs what every Android module needs: a namespace and SDK levels. It comes from Android's own plugin for shared modules, the second line under plugins. (Before version 8.12 of that plugin, the block was called androidLibrary { }; you'll still see it in older projects.)

iOS takes two lines. Puzzle 0 called iOS one target; that was a simplification, and here is the full picture. A target is one exact kind of binary, and an iPhone and the simulator need different ones. The simulator is Apple's stand-in iPhone that runs on your Mac, like the Android emulator. iosArm64 builds for real iPhones; iosSimulatorArm64 builds for the simulator on a Mac with Apple's own chip. Declare only the device target, and Kotlin's docs warn you can't run your app or its tests on your own machine.

Every target gets a platform source set: a source set compiled for that one target, named after it. Android's is androidMain, the one puzzle 1 showed. The iOS targets get iosArm64Main and iosSimulatorArm64Main.

And every target is built by compilations. A compilation is one compiler run for one target, over every source set that target uses. Each iOS target has two by default: main, for your code, and test, for your tests, which live in commonTest (tests for every target) and the target's own test source set, such as iosArm64Test. Android's compilations are set up by Android's own plugin instead, but play the same two roles.

So the main compilation of iosArm64 takes commonMain and iosArm64Main and compiles them together. (That's still slightly simplified: the next puzzle adds the source sets in between.) Notice what's missing from the list: there's no iosMain, because no target is called ios. The next puzzle shows where it comes from.

The analogy

The company from puzzle 1 opens offices: the kotlin { } block is the list. "iOS" turns out to be two offices: the real one downtown, and a training office inside headquarters, where staff practise on a stand-in (the simulator). Each office keeps its own local folder (its platform source set), and each prints its handbook in two editions: one for staff, one for the inspectors who test it (the main and test compilations).

Check yourself

You declare only iosArm64() for iOS, then try to run the shared tests in the simulator on your Mac. What happens?

Not quite. A target is one exact kind of binary; the simulator needs its own, iosSimulatorArm64.

Right. Device and simulator are two different targets.

Not quite. commonTest is compiled per declared target; with no simulator target there's no binary for the simulator at all.

Why does a module that runs on "Android and iOS" declare three targets?

Not quite. Both iOS targets compile your Kotlin; they differ in where the binary runs.

Right. One target per kind of binary.

Not quite. There's no spare: every target produces its own binary, for its own machine.

What's the difference between a target and a compilation?

Not quite. That's the two swapped.

Right. What you build for vs one run that builds it.

Not quite. Each iOS target has at least two compilations: main and test.

Sources
  • Kotlin docs: The basics of Kotlin Multiplatform project structure ("In Gradle, you declare targets using predefined DSL calls inside the kotlin {} block"; "Device target is used to generate binaries that can be executed on iOS devices"; "Simulator target is used to generate binaries for the iOS simulator launched on your machine. If you have an Apple silicon Mac computer, choose iosSimulatorArm64 as a simulator target"; "If you declare only the iosArm64 device target, you won't be able to run and debug your application and tests on your local machine"; "Each target has a corresponding platform source set that compiles for only that target")
  • Kotlin docs: Multiplatform Gradle DSL reference ("The fully qualified name of the Kotlin Multiplatform Gradle plugin is org.jetbrains.kotlin.multiplatform"; "Each target can have one or more compilations"; "Predefined compilations are created automatically for each target of a project except for Android targets")
  • Kotlin docs: Advanced concepts of the multiplatform project structure ("Kotlin Multiplatform projects require multiple compiler launches to build all the artifacts. Each compiler launch is a Kotlin compilation"; "By default, Kotlin creates two compilations for each target, the main compilation for production sources and the test compilation for test sources")
  • Android docs: Set up the Android Gradle Library Plugin for KMP ("Within the kotlin block, specify the Android target using android"; "Starting with AGP 8.12.0, a new android{} block was introduced to replace androidLibrary{}")

What you now know

The kotlin { } block, read by the multiplatform plugin, declares the module's targets. iOS needs at least two, iosArm64 for real iPhones and iosSimulatorArm64 for the simulator on a Mac, because each target is one exact kind of binary. Every target gets its own platform source set, named after it, and is built by compilations, one compiler run each: main for your code, test for your tests.