CoursesKotlin Multiplatform, from the compiler up

Puzzle 19 · 20 of 20

Dependencies per source set

In an Android module, every library goes into one dependencies block for the whole module. In a shared module, the source set you add a library to decides which code can use it. Here's where each kind of library goes.

All puzzles in this course

The problem

Puzzle 18 said a source set sees the code above it. Your shared code needs libraries too: an HTTP client everywhere, Android's OkHttp underneath it on Android, Apple's own networking on iOS. In an Android module, you'd add all of them to the one dependencies { } block, and every class in the module could use every library. Where do they go when the module is compiled for three targets, and some libraries only exist on one of them?

See it

Ktor's core library drops into commonMain and flows down to androidMain and iosMain; Ktor's OkHttp part goes into androidMain and its Darwin part into iosMain; the OkHttp part put into commonMain fails, because it has nothing for iOS commonMain androidMain iosMain ktor-client-core ktor-client-corektor-client-core ktor-client-okhttp ktor-client-darwin ktor-client-okhttp no iOS build

Scroll sideways to see the full diagram.

  1. Each source set has its own dependencies. Ktor's core is a multiplatform library, published for every target with one common API, so it can go into commonMain.

    Step 1 of 5
  2. Added once, it flows down every link: androidMain and iosMain can use it too, without a line of their own.

    Step 2 of 5
  3. Ktor also has parts built for one platform: one sends requests with OkHttp on Android, one with Apple's own networking. Predict: where does each go?

    Step 3 of 5
  4. Each into its own platform's source set. A library added there flows down too, but never up or sideways.

    Step 4 of 5
  5. The OkHttp part in commonMain instead? The build fails: commonMain must compile for iOS too, and that part has no iOS build.

    Step 5 of 5

The building block

Each source set has its own dependencies, declared inside kotlin { }:

kotlin {
    // the targets from puzzle 16 …
    sourceSets {
        commonMain.dependencies {
            implementation("io.ktor:ktor-client-core:3.6.1")
        }
        androidMain.dependencies {
            implementation("io.ktor:ktor-client-okhttp:3.6.1")
        }
        iosMain.dependencies {
            implementation("io.ktor:ktor-client-darwin:3.6.1")
        }
        commonTest.dependencies {
            implementation(kotlin("test"))
        }
    }
}

You can write iosMain.dependencies without creating iosMain: the default template from puzzle 17 already made it, and the plugin gives every template source set a name you can use in the build file.

A library added to a source set flows down the dependsOn links from puzzle 18: every source set below gets it too. Ktor's core, added to commonMain once, can be used in androidMain, nativeMain, appleMain, iosMain and both iOS platform source sets. Add a library to iosMain instead, and only the iOS source sets can use it. The one library you never add is Kotlin's standard library: every source set gets it automatically.

commonMain only accepts a multiplatform library: one published for all of commonMain's targets, with one common API that common code can call. Kotlin's coroutines, Ktor's core and SQLDelight are multiplatform libraries. A library built for one platform only goes into that platform's source set. Ktor shows both kinds: the part that actually sends requests is per platform, ktor-client-okhttp for Android (built on OkHttp, a library for the JVM and Android) and ktor-client-darwin for Apple's systems (built on Apple's own networking). Put the OkHttp part in commonMain and the build fails: commonMain must compile for iOS too, and that part has nothing for iOS.

Two more lines you'll meet in the code above. The kotlin("test") line in commonTest gives every test source set Kotlin's multiplatform test library. And another multiplatform module of your own goes in the same way, with a project line in commonMain, and every target gets its matching part.

The analogy

Supplies for the offices from puzzle 17. A supply ordered for the shared handbook's level reaches every office below it, so it must be something every country can use, like a standard pen. A local supply, like a plug adapter that only fits Japan's wall plugs, is ordered at the Japan folder's level, and only offices under it receive it. Order the adapter for everyone and the order fails: France can't use it.

Check yourself

You add OkHttp, a library built only for the JVM and Android, to commonMain.dependencies. What happens when you build for iOS?

Not quite. A library arrives already built for its platforms; Kotlin/Native can't make an iOS one from it.

Right. commonMain takes only libraries built for all its targets.

Not quite. commonMain is compiled for every target; nothing is skipped on iOS, it just doesn't compile.

Why can iosMain use a library you added only to commonMain?

Not quite. There's no copy: the library flows down the dependsOn links.

Right. Libraries flow down the links.

Not quite. Only the standard library comes for free; this one you added yourself. Re-read that part ↑

What's the difference between a multiplatform library and a library built for one platform?

Not quite. The language isn't it: a Kotlin library built only for Android can't go into commonMain either. Re-read that part ↑

Right. Where each one may go.

Not quite. The other way round: a multiplatform library added to commonMain reaches every source set below.

Sources
  • Kotlin docs: Adding dependencies on multiplatform libraries ("The main difference is that you need to add the dependency to a specific source set rather than to the module as a whole"; "Multiplatform dependencies. These are multiplatform libraries that support multiple targets and can be used in the common source set"; "The common source set can't depend on platform-specific artifacts: common code needs to compile for every declared target"; "Each source set in a Kotlin Multiplatform project automatically depends on the Kotlin standard library"; "Makes kotlin.test classes available in all test source sets")
  • Kotlin docs: Advanced concepts of the multiplatform project structure ("Multiplatform dependencies are propagated down the dependsOn structure. When you add a dependency to commonMain, it will be automatically added to all source sets that declare dependsOn relations directly or indirectly in commonMain")
  • Kotlin docs: Source set hierarchy ("The Kotlin Gradle plugin provides both type-safe and static accessors for all of the source sets from the default hierarchy template")
  • Ktor docs: Client engines ("For multiplatform projects, you can use Ktor's default engines or select specific engines for individual targets"; supported platforms: "OkHttp JVM, Android Darwin Native"; "The Darwin engine targets Darwin-based operating systems, such as macOS, iOS, tvOS, and watchOS. It uses NSURLSession under the hood")

What you now know

Each source set has its own dependencies block, and a library added to a source set flows down to every source set below it. commonMain may only take multiplatform libraries, published for all of its targets with one common API. A library built for one platform goes into that platform's source set, such as androidMain or iosMain.

Apply what you learned

Continue with worked examples and practice cases. When you reach the final project, make your own decisions before comparing your evidence with the worked review.

Continue to Design and verify a shared library boundary → Start the final project →