Our Kotlin Multiplatform implementation

In my last post "Our use case of using Kotlin Mutliplatform" I described how my team and I use Kotlin Multiplatform. This time — as promised in the last post — I’ll share some code with you so that you can directly jump into it and start by yourself. Additionally I have a nice GitHub template for you as well.

Everything starts by opening IntelliJ, right? No, I always go a different way. Because even if these "project setup assistant wizards" get better and better I think they will just introduce some kind of "overhead". Especially if you want to start with a new technology. So instead of using these wizards (or even opening IntelliJ) I open my terminal and setup Gradle together with all the directories which are required by this project.

mkdir awesomeMultiplatform 
cd awesomeMultiplatform
gradle wrapper
vi build.gradle.kts

Yes, I have installed Gradle on my machine for only these reasons.

But what does belong to the build.gradle.kts?
The minimal setup for the JVM and the iOS targets is the following:

import org.jetbrains.kotlin.gradle.tasks.FatFrameworkTask
plugins {
  kotlin("multiplatform") version "1.3.60"    
}
val frameworkName = "SomeFrameworkName"
kotlin {
  jvm()
  iosArm64 { 
    binaries.framework {
      baseName = frameworkName        
    }
  }
  iosX64 { 
    binaries.framework {
      baseName = frameworkName        
    }
  }
}
repositories {    
  mavenCentral()
}
val jvmMainImplementation by configurations
dependencies {
  commonMainImplementation(kotlin("stdlib-common"))
  jvmMainImplementation(kotlin("stdlib-jdk8"))
}
tasks.register("releaseFatFramework", FatFrameworkTask::class) {
  baseName = frameworkName
  from(
    kotlin.iosArm64().binaries.getFramework("RELEASE"),
    kotlin.iosX64().binaries.getFramework("RELEASE")
  )
}

Well, that's a lot which requires some explanation I guess. So let's split it into smaller pieces.

Please always keep in mind that we build a library which is for the JVM world a good old JAR file while in the iOS world a Framework.

The Kotlin block/extension

After you apply the multiplatform plugin you can setup the kotlin {} block with the targets you want to create.

A target is the "piece" you want to build. Well, for instance, if you want to have a JAR file at the end, then you need a jvm target. If you want to have a Framework then you need an ios target. And this is what we declare in the build script above.

We declare three targets: jvm(), iosArm64() and iosX64() while the two iOS targets requires additional setup so that the plugin build a Framework. Otherwise it wouldn't build a Framework but something else. For instance an macosX64 target could be built as an executable which will result in an executable file which can be… well, executed.

Why two iOS targets and the FatFrameworkTask

We have two iOS targets because our library should run on real iOS devices (like an iPhone or an iPad) and on iOS simulators. Both platforms run on different architectures. Simulators are running probably on your Mac and using the CPU of it. The CPU of your Mac is a x64. On the other hand iOS devices are powered by an arm64 CPU. Therefore we need both targets to run on both CPU architectures.

Yes, this leads to the fact that we will have two Frameworks produced by our build task. A consequence is that the iOS team should deal with it and implement a build step like "if I deploy to the simulator, attach the x64 Framework, otherwise use the arm64 Framework".

Because we are all lazy and don't want to implement a build step like this we could also create a so called FatFramework. What it does is — saying naively— to simply put both Frameworks into one. The iOS guys don't have to deal with the if/else switch but can import only the FatFramework. The app will then run on real devices and on simulators.

Because this is not the default if you setup multiple iOS targets in the kotlin block you have to set the baseName for each target and setup the FatFrameworkTask like I did at the end of the build script.

Dependencies

You require at least two dependencies for this kind of setup. For the shared (or common) world the stdlib-common and for the JVM world one of the stdlib-jvmX.

There is no need to setup any special dependencies for the iOS (or native) world because all "dependencies" which are supported by Kotlin/Native are magically available.

Without any dependency setup. Some libraries are already pre-imported into the K/N compiler package.

Before I forget to mention it. You may see a different way of declaring dependencies in other tutorials (or even in the official docs). Both ways are totally fine and are working. I personally prefer this way because it is more Gradleish and doesn't look that weird (to me).

Only that you have also seen it. The following is a one to one replacement for the dependencies block above):

kotlin {
  // .. setup the targets
  sourceSets {
    named("commonMain") {
      dependencies {
        implementation(kotlin("stdlib-common"))
      }
    }
    jvm().compilations["main"].defaultSourceSet {
      dependencies {
        implementation(kotlin("stdlib-jdk8"))
      }
    }
}

SourceSets/Directories

Each declared target will create a sourceSet in a special pattern. The following shows the directories I created:

.
|—- src
    |-- commonMain
    |-- iosArm64Main
    |-- iosX64Main
    |-- jvmMain

You may notice that the name of the sourceSet is equal to the target name plus "Main". There will also be test sourceSets created which are named in the same pattern but end with "Test".

Testing

Now you're basically done with the setup and you can finally open IntelliJ and start coding 👨‍💻. But before you leave this post I would like to explain the topic testing a little bit more in detail because I think this needs some attention as it is a little bit different.

First of all, as also mentioned above, you have for each target a test sourceSet. This means there exists a commonTest sourceSet where you can place your tests for the common code. But this also requires test dependencies:

val jvmTestImplementation by configurations
dependencies {
  commonTestImplementation(kotlin("test-common"))
  commonTestImplementation(kotlin("test-annotations-common"))
  jvmTestImplementation(kotlin("test:1.3.60"))
  jvmTestImplementation(kotlin("test-junit:1.3.60"))
}

Again, the test dependency for the native code is already built in.

There is nothing special until up to this point. But you may ask yourself "Why do I have to add dependencies to the targets (to jvm and ios even if the latter is invisible)?". I would respond with "Great question!".

This is because your tests have to run "on a target". If you run your common tests they have to run either on a JVM or natively. And this is the reason why there is no commonTest Gradle task but only a jvmTest task. The task runs the tests inside the commonTest sourceSet (and if available the jvmTest sourceSet of course) on a JVM.

For some reasons there is no iosX64Test or iosarm64Test task. But you want to test the common native implementation (meaning running the commonMain code in a native environment) as well, right? Because it runs with Kotlin/Native (instead of Kotlin/JVM) under the hood and this may behave differently in some situations.

We "workaround" this by simply adding a macosx64 target. Because this will add a macosX64Test task to Gradle which then runs the commonMain code (and if available the macosx64 sourceSet of course) natively.

Publishing

As mentioned in my previous post we have a separate repository with our Multiplatform implementation. Therefore, to consume the JAR and the Framework, they have to be published somewhere. We are using our internal Artifactory for it.

Publish the JAR

On the JVM side this is pretty easy to implement because the Gradle Plugin provides basically everything we need to publish the JAR as a maven artifact. The only few lines of code we have to write is — beside of applying the Gradle maven-publish plugin — to tell the plugin where we want to publish the artifacts:

pluginManager.apply("maven-publish")

extensions.getByType(PublishingExtension::class.java).apply {
  repositories { repoHandler ->
    repoHandler.maven {
      it.name = "Artifactory"
      it.url = project.uri("https://artifactory.url")
      it.credentials { 
        it.username = "UserName"
        it.password = properties["artifactoryKey"] as? String
      }
    }
  }
}

We have abstracted this code in a Gradle plugin in the buildSrc directory. But you can also add these lines — with a slightly different syntax of course — to your build script as well.

That's it for the JVM side. Now you have a task called publishJvmPublicationToArtifactoryRepository which will, by executing it, publish the JAR to the Artifactory.

Publish the Framework

To publish the generated Framework we require a little bit more code — or at least I haven't found another way yet. I know there is also a CocoaPods Plugin but our iOS guys use Carthage these days and therefore I can't make use of it.

Anyway, even if we have to implement it by ourself the logic is quite easy.

1. First we need a task which depends on the "FatFramework generation" task and ZIP it.
2. An additional task depends on the ZIP task and publish the Framework. We are using the jfrog CLI for it. But you could of course make this independent from any tools and use OkHttp if you like.
3. For Carthage we need a JSON file which is basically a mapping from "version to location of the Framework of this version". The JSON file has to be created (or download if already available at the Artifactory) and updated with the new version.
4. Finally we have to publish the JSON file to the Artifactory as well.

Cause this is a lot of code I extracted this into this GitHub Gist instead of inlining it here.

I know this is not the most elegant solution and even the code could be polished but for now it works 🙃.

Wuzaa. A lot of text without having the promised GitHub template in sight where you can see all the stuff connected in action.

So, here we go:

StefMa/KotlinMultiplatformTemplate

Even if I'm not sure if and how I will improve this repository feel free to create issues or get in touch with me over Twitter.

I hope you enjoyed this post and I will see more and more companies or indie developers jumping on the Kotlin Multiplatform train 🚋 which hopefully make our lives easier in the future.