Kotlin Multiplatform, from the compiler up · Puzzle 3 · 4 of 16

A promise and its keepers

In puzzle 1, common code couldn't call a platform's own APIs. But shared logic sometimes needs a small platform fact, like which phone it's running on. Here's how it asks without knowing.

The problem

In puzzle 1, common code could only use what every target has. But your shared logging code wants to print which platform it's on: "Android 34" or "iOS 17". Each platform has its own way to tell, and common code can't call either. How does common code use something only the platforms have?

See it

Common code declares an expect function with no body; androidMain and iosMain each provide an actual; the compiler plugs the right one into each target; a target without an actual fails to build commonMainexpect platformName() no body androidMainactual: "Android 34" iosMainactual: "iOS 17" Android 34 web: no actual
  1. Common code makes a promise: platformName(), marked expect, with no body. It can call it without knowing how it works.

    Step 1 of 4
  2. Each platform keeps the promise with an actual, written with its own APIs: Android's build number, Apple's system version.

    Step 2 of 4
  3. When the compiler builds the Android target, it plugs in Android's actual. Predict: what if a target has no actual?

    Step 3 of 4
  4. That target's build fails. The compiler checks every promise is kept, so none can be forgotten.

    Step 4 of 4

The building block

Common code makes a promise. It declares what it needs, without a body, marked expect:

// commonMain
expect fun platformName(): String

Then every platform source set keeps that promise with an actual declaration, using its own APIs:

// androidMain
actual fun platformName(): String = "Android ${Build.VERSION.SDK_INT}"

// iosMain
actual fun platformName(): String = UIDevice.currentDevice.systemName() + " " + UIDevice.currentDevice.systemVersion

Common code calls platformName() like any function. When the compiler builds a target, it plugs in that target's actual. And it checks: if one target has no actual, that target's build fails, so a promise can't be forgotten.

expect and actual work best for small things like this. For bigger platform services, like storage or a network client, the usual choice is an interface in common code with one implementation per platform, handed in from outside: it does the same job, and in a test you can hand in a fake.

The analogy

The shared handbook from puzzle 1 says: "Call the local tax office." It doesn't say which. Each country's office fills in its own number. Before the handbook is printed for a country, someone checks that number is filled in.

Check yourself

You add a web target. platformName() has actuals for Android and iOS only. What happens?

Not quite. There's no default: the compiler requires an actual for every target.

Right. Every target must keep the promise.

Not quite. One platform's actual is never used for another; each target needs its own.

Why mark it expect instead of writing an if that checks the platform in common code?

Not quite. Speed isn't it: common code can't reach the platforms' APIs at all. Re-read that part ↑

Right. The platform calls must live where those APIs exist.

What's the difference between an expect declaration and an actual one?

Not quite. Every platform, Android included, writes its own actual.

Right. A promise, and its keepers.

Not quite. An expect has no body at all: only the actuals do the work.

Sources

What you now know

An expect declaration in common code is a promise; every platform source set keeps it with an actual declaration. The compiler checks that every target has one. For anything bigger, an interface implemented per platform does the same job and is easier to test.