DEV Community: Ekaterina Petrova

Publishing your Kotlin Multiplatform library to Maven Central

Ekaterina Petrova — Thu, 25 Mar 2021 12:40:40 +0000

Now when we've built our first Kotlin Multiplatform library and learned about multiplatform library publishing format nothing can stop us from going public and releasing our library to MavenCentral!

Registering a Sonatype account

If this is your first library, or you’ve only ever used Bintray to do this before, you will need to first register a Sonatype account.

There are many articles describing the registration process on the internet. The one from GetStream is exhaustive and up to date. You can start by following the first four steps, including "Generating a GPG key pair":

Register a Jira account with Sonatype (you can use my issue as an example). ✅
Verify your ownership of the group ID you want to use to publish your artifact by creating a GitHub repo. ✅
Generate a GPG key pair for signing your artifacts. ✅
Publish your public key. ✅
Export your private key. ✅

When the Maven repository and signing keys for your library are prepared, we are ready to move forward and set up our build to upload the library artifacts to a staging repository and then release them!

Setting up publication

Now we need to tell Gradle how to publish our libraries. Most of the work is already done by maven-publish and Kotlin Gradle Plugins – all the required publications are created automatically. We've already seen the result when we published our library to the local Maven repository. But for publishing it to Maven Central we need to take some additional steps:

Configure public Maven repository URL and credentials.
Provide a description and javadocs for all library components.
Sign publications.

Let's handle all of these tasks by writing some Gradle scripts! I suggest extracting all the publication-related logic from our library module build.script, so you can easily reuse it for other modules in the future.

The most idiomatic and flexible way to do that is to use Gradle’s precompiled script plugins. Our build logic will be provided as a precompiled script plugin and could be applied by plugin ID to every module of our library.

To implement this, we need to put our publication logic into a separate Gradle project:

Add a new gradle project convention-plugins inside your library root project by creating a new folder named
convention-plugins with build.gradle.kts in it.

Put the following in the build.gradle.kts:

plugins {
    `kotlin-dsl` // Is needed to turn our build logic written in Kotlin into Gralde Plugin
}

repositories {
    gradlePluginPortal() // To use 'maven-publish' and 'signing' plugins in our own plugin
}

Create a convention.publication.gradle.kts file in the convention-plugins/src/main/kotlin directory. This is where all the publication logic will be stored.

Put all the required logic there. Applying just maven-publish is enough for publishing to the local Maven repository, but not to Maven Central. In the provided script we get the credentials from local.properties or environment variables, do all the required configuration in the ‘publishing’ section, and sign our publications with the signing plugin:

import org.gradle.api.publish.maven.MavenPublication
import org.gradle.api.tasks.bundling.Jar
import org.gradle.kotlin.dsl.`maven-publish`
import org.gradle.kotlin.dsl.signing
import java.util.*

plugins {
   `maven-publish`
   signing
}

// Stub secrets to let the project sync and build without the publication values set up
ext["signing.keyId"] = null
ext["signing.password"] = null
ext["signing.secretKeyRingFile"] = null
ext["ossrhUsername"] = null
ext["ossrhPassword"] = null

// Grabbing secrets from local.properties file or from environment variables, which could be used on CI
val secretPropsFile = project.rootProject.file("local.properties")
if (secretPropsFile.exists()) {
   secretPropsFile.reader().use {
       Properties().apply {
           load(it)
       }
   }.onEach { (name, value) ->
       ext[name.toString()] = value
   }
} else {
   ext["signing.keyId"] = System.getenv("SIGNING_KEY_ID")
   ext["signing.password"] = System.getenv("SIGNING_PASSWORD")
   ext["signing.secretKeyRingFile"] = System.getenv("SIGNING_SECRET_KEY_RING_FILE")
   ext["ossrhUsername"] = System.getenv("OSSRH_USERNAME")
   ext["ossrhPassword"] = System.getenv("OSSRH_PASSWORD")
}

val javadocJar by tasks.registering(Jar::class) {
   archiveClassifier.set("javadoc")
}

fun getExtraString(name: String) = ext[name]?.toString()

publishing {
   // Configure maven central repository
   repositories {
       maven {
           name = "sonatype"
           setUrl("https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/")
           credentials {
               username = getExtraString("ossrhUsername")
               password = getExtraString("ossrhPassword")
           }
       }
   }

   // Configure all publications
   publications.withType<MavenPublication> {

       // Stub javadoc.jar artifact
       artifact(javadocJar.get())

       // Provide artifacts information requited by Maven Central
       pom {
           name.set("MPP Sample library")
           description.set("Sample Kotlin Multiplatform library (jvm + ios + js) test")
           url.set("https://github.com/KaterinaPetrova/mpp-sample-lib")

           licenses {
               license {
                   name.set("MIT")
                   url.set("https://opensource.org/licenses/MIT")
               }
           }
           developers {
               developer {
                   id.set("KaterinaPetrova")
                   name.set("Ekaterina Petrova")
                   email.set("ekaterina.petrova@jetbrains.com")
               }
           }
           scm {
               url.set("https://github.com/KaterinaPetrova/mpp-sample-lib")
           }

       }
   }
}

// Signing artifacts. Signing.* extra properties values will be used

signing {
   sign(publishing.publications)
}

Go back to your library project. Ask Gradle to prebuild your plugins by adding the following in the root settings.gradle:
```
includeBuild("convention-plugins")
```
Now we can apply this logic in our library build.script. In the plugins section, replace using maven-publish with using our conventional.publication.
```
plugins {
   kotlin("multiplatform") version "1.4.30"
   id("convention.publication")
}
```
Don’t forget to create a local.properties file with all the necessary credentials and make sure you have added it to .gitignore 🗝:
```
signing.keyId=...
signing.password=...
signing.secretKeyRingFile=...
ossrhUsername=...
ossrhPassword=...
```

Now take a deep breath, make ./gradlew clean and sync the project.

New Gradle tasks related to the Sonatype repository should appear in the publishing group – that means that everything is ready for you to publish your library!

Publishing your first library to MavenCentral

In the beginning of the article I promised you that you will be able to publish your library in just a one click – and now is the moment of truth! To upload your library to Sonatype Repository just run:

./gradlew publishAllPublicationsToSonatypeRepository

The so-called staging repository will be created, and all the artifacts for all publications will be uploaded to that repository. All that is now needed is to check that all the artifacts you wanted to upload have made it there and to press the “release” button!

These final steps are well-described in the now-familiar article. In short, you need to:

Go to https://s01.oss.sonatype.org/ and log in using the credentials you used in Sonatype Jira.
Find your repository in the ‘Staging repositories’ section.
Close it.
🚀 Release it!

Go back to the Jira Issue you created and let them know you released your first component to activate the sync to Maven Central. This step is needed only if it’s your first release.

Soon your library will become available at https://repo1.maven.org/maven2/ and other developers will be able to add it as a dependency. And in a couple of hours, it will become discoverable in Maven Central Repository Search!

Conclusion

Congratulations! 🎉 You’ve just created your first Kotlin Multiplatform Library and published it on Maven Central!

This is how you can now depend on the published version:

kotlin {
    android()
    ios ()
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.github.katerinapetrova:mpp-sample-lib:1.0.0")
            }
        }
}

Pretty simple, right? If you check the external dependencies section, you will see that it is quite clever as your project only downloads the artifacts of the platforms you actually target, not all of them every time. Thanks to the Gradle module metadata feature, you only have to specify dependencies on the library once in the shared source set, even if it is used in platform source sets.

A lot of work has been done, but of course, it’s just the beginning of the journey. The most interesting part is ahead: to support and improve your library continuously, so you can provide your users the best DX and evolve the KMM ecosystem together with other library creators and contributors.

Next useful steps

Now that you have published your library to Maven Central, it's time to let others know – and what better way than to add a badge to your project's README!
Add your library to the community-driven list of Kotlin Multiplatform libraries to increase its discoverability.
Take a look into the possibility to automate the release process and share your experience with the community, if you’ve already successfully made it this far!

KaterinaPetrova / mpp-sample-lib

Sample Kotlin Multiplatform library (jvm + ios + js)

How a Kotlin Multiplatform library is published?

Ekaterina Petrova — Thu, 25 Mar 2021 12:40:27 +0000

In the first part of the series, we've created our first multiplatform library and published it to the local Maven. Before going public, let's discover published artifacts to get an understanding of the multiplatform publishing format.

TL;DR: The Kotlin Gradle plugin creates and configures your library publications automatically, so you don't need to know the details of the publication scheme to successfully deliver your library. But if you are curious, let's discuss it a little!

Discovering your library structure

If you have published regular platform (for example, android) libraries before, you may notice that the publishing format of a multiplatform library differs quite a lot. There are multiple artifacts for one version of your library, their content format is different (.jar vs .klib), and the number of source sets doesn’t match the number of result artifacts.

This is because ordinary publishing is not enough for a multiplatform library. Multiplatform libraries have more complex structures compared to normal ones, so the publication is less trivial as well. Here are key differences to keep in mind:

Multiplatform libraries consist of multiple parts: common parts with expects declarations and platform-specific parts with actual implementations.
Platform-specific code may still be shared across similar platforms (e.g. in a source set shared between the iOS device and simulator, or shared code for all desktop platforms).
There should be the ability to publish all those parts from a multiple host because of Kotlin/Native cross-compilation limitations. For example, the artifacts for iOS or macOS can be built only on Mac-OS.

Considering all that complexity, adding the ordinary multiplatform dependency requires just a single line of code in your the build.gradle file:

dependencies {
    implementation("io.github.katerinapetrova:mpp-sample-lib:1.0.0")
}

So how does this magic work? Maven doesn’t operate with targets, source sets, and compilations. It operates only with projects. A project is everything we build and could depend on. Each project is defined by groupId, artifactId, and version, and these three fields are used by Maven as a coordinate system. This is exactly what you are using when copy-pasting a dependency string to your build.gradle file. These coordinates are defined in a .pom file — an XML representation of a Maven project. Let’s take a look at what we have in the local Maven folder of the library we’ve just published:

We published only one library, but there are multiple folders. Each folder represents a separate maven project, containing different artifacts and a .pom file, which describes the project (we can also call them “artifacts”, as the name of the project is stored in the POM artifactId field).

So the Kotlin Gradle plugin has created publications, which were used by the maven-publish plugin to map the sources of our Kotlin Multiplatform library to the Maven artifacts, on which we later could depend on in the consumer project as Gradle modules. This is how it was done:

Let’s figure out the main points of this transformation:

There is a separate publication for each target. The binary format depends on the target compiler backend:
- .jar with class files for Kotlin/JVM
- .jar with .js or .klib when using IR Compiler for Kotlin/JS
- .klib for Kotlin/Native
There is also an additional root publication that stands for the whole library. It consists of two important parts:
- Kotlin representation of common sources of your library. Kotlin toolchain will use it to provide exact and granular dependencies from your common code to a library's common code.
- Gradle Module Metadata, which tells Gradle where to find other platform-specific parts of a library when you depend on the root artifact in the common source set. This is what allows you to write single-line dependency on a library in a common source set
With the hierarchical project structure enabled, the API of the library’s intermediate source sets is embedded into the library artifacts (common or platform, depending on which targets this set is divided between).

This transformation doesn’t look trivial and the described points are just the tip of the iceberg, but the good news is that all the work is done by the Kotlin Gradle plugin. It creates and configures all the relevant publications automatically, so you don't need to create them manually. That significantly reduces the chance of making a mistake, especially for popular configurations. 🎉

If you want to dive into the details of publication format, I suggest you watch an exciting talk by Dima Savinov, Kotlin Multiplatform team lead.

And now let’s go back to our main goal — making our library available to the world! Check out the last part of the series, which will guide you through the MavenCentral publication process 👀

Creating your first Kotlin Multiplatform library

Ekaterina Petrova — Thu, 25 Mar 2021 12:40:04 +0000

Kotlin multiplatform technology is becoming more and more popular and the ecosystem is changing rapidly. Have you ever wondered about creating a multiplatform library? Now is a great time to start creating one, as there are a lot of open needs in the community and your involvement will be highly appreciated!

Of course, writing good code and providing useful API should be your top priority as a library author. But if you are publishing your library for the first time, there are some obstacles you’ll need to overcome. For example, as Bintray is shutting down in May 2021, you have to handle the Maven Central registration process and configure your library for publishing there.
This post will help you through the multiplatform library publishing routine giving you one less thing to worry about so that you can concentrate on the library itself 🧘🏼‍♀️

Plan

In the first part of the series we are going to create a multiplatform library that uses platform APIs with expect/actual mechanism, provides a simple API to the users, and supports three targets: Native (iOS or your host machine target, depending on your choice), JVM, and JavaScript. Such a library can be used in any KMM (Kotlin Multiplatform Mobile) or other Kotlin Multiplatform projects.

If you already have a project you want to publish, you can jump directly to the final step of this part – publishing the library to the local Maven repository to make sure that everything works correctly. In the next part, we will also discover published artifacts to get an understanding of the multiplatform publishing format. Finally, in the last part of the series, we will register a Sonatype account that is needed to publish your library to MavenCentral.

🤔 If you are feeling a little confused with all the new Maven terminology we are throwing around – it's okay! Here’s a useful twitter tip, which might help!
// Detect dark theme var iframe = document.getElementById('tweet-1357436828861759491-933'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1357436828861759491&theme=dark" }

Next, we will set up the mechanism for publishing your project so you'll be able to configure, sign, and publish a library by calling a single Gradle task. Finally, we will publish your library in MavenCentral so that it will become available to developers all over the world!

There is lots to do, so let's get started!

ℹ️ Disclaimer: This tutorial is based on official documentation and other existing articles. They all provide useful and up-to-date instructions, but they don't fully cover the bumpy, winding road that is the publishing process. Here you will find a combination of the most relevant existing content and additional information, which should answer all your questions.

Setting up the environment

If you want your library to support iOS or macOS targets, you need a macOS to build the native artifacts. But otherwise, you can build your library on any operating system.
I will be demonstrating using IntelliJ IDEA (download the latest version here) with the latest Kotlin plugin, but you can use Android Studio as well. IntelliJ IDEA comes with a few useful Kotlin wizards, including a multiplatform library wizard.
For creating the GPG keys that are needed to sign your library, we will use the GPG command-line tool. Download and install it manually, or with package management utilities, for example, brew: brew install gpg

Alright, that’s enough introduction and preparing — let’s start!

Creating a multiplatform library

To publish something, we first need to build something! If you don't have a library yet, but you want to get some hands-on experience publishing one, let’s start by creating a sample library following the official tutorial, which describes the process of developing a multiplatform library from scratch.
In this tutorial, you will learn how to create a multiplatform library for JVM, JS, and Native platforms, write common tests for all the platforms, and publish the library to a local Maven repository. This library will convert raw data – strings and byte arrays – to Base64 format. To implement the conversion to the Base64 format on the different platforms, you will use the platform capabilities for JVM and JS, and write your own implementation for Native.

Supporting iOS target

This tutorial demonstrates building a library that supports native target equals your host target (so if you develop on macOS, then the resulting native artifact will be suitable for running on macOS). However, you can easily configure the supported targets set. For example, you can add the iOS target to make your library suitable for KMM projects. There are two ways to do this:

If you don’t need to support your host target and need only iOS, you could replace the host-dependent native target declaration that was generated by the project wizard with the ios() target declaration:

// Before
kotlin {
    jvm {
       // …
    }
    js(IR) {
       // …
    }
    val hostOs = System.getProperty("os.name")
    val isMingwX64 = hostOs.startsWith("Windows")
    val nativeTarget = when {
        hostOs == "Mac OS X" -> macosX64("native")
        hostOs == "Linux" -> linuxX64("native")
        isMingwX64 -> mingwX64("native")
        else -> throw GradleException("Host OS is not supported in Kotlin/Native.")
    }
}

// After
kotlin {
    jvm {
      // …
    }
    js(IR) {
      // …
    }
    ios()
}

Don’t forget to also rename source set declarations and folder names according to the target name (nativeMain -> iosMain in our case).

If you want to support both your host and iOS native targets and share code between them, you should manually configure the hierarchical project structure.

Supporting Android target

This tutorial uses jvm() target declaration for JVM platforms support. The resulting artifact could be used in multiplatform projects that target any JVM platforms, including Android. If you want to make it possible to use your library directly from the Android project, or you need to use Android SDK to implement platform-specific features (for example, working with files stored on the device), use the android() target declaration instead. To make it work, you need to connect the android-library Gradle plugin and provide Android-specific information in the android configuration block in the build.gradle.kts:

android {
    compileSdkVersion($compileSdkVersion) 
 sourceSets["main"].manifest.srcFile("src/androidMain/AndroidManifest.xml") // Create AndroidManifest.xml and provide path to it
    defaultConfig {
        minSdkVersion($minSDKVersiom)
        targetSdkVersion($targetSDKVersion)
    }
}

Additionally, you need to specify the variant names in the Android target, as no artifacts of an Android library are published by default (see official docs for the details).

kotlin {
    android {
        publishLibraryVariants("release", "debug")
    }
}

Complete the Create and publish a multiplatform library tutorial and configure the targets according to your needs. Here is the source code of the sample Base64 library with JVM, JS, and iOS support:

KaterinaPetrova / mpp-sample-lib

Sample Kotlin Multiplatform library (jvm + ios + js)

Now we push on to the next stage and publish our library!

Publishing your library to the local Maven repository

The only difference from developing a regular multiplatform module is using the maven-publish Gradle plugin. When used with maven-publish, the Kotlin plugin automatically creates publications for each target that can be built on the current host (doc). Using the corresponding Gradle tasks provided by the maven-publish plugin, you can deploy these publications to a remote or local repository.

If you already have a code you want to publish, then all you need is to apply maven-publish and provide the library group and version information (see the last step of the tutorial).

plugins {
    kotlin("multiplatform") version "1.4.31"
    id("maven-publish")
}

group = "org.jetbrains.base64"
version = "1.0.0"

Running ./gradlew publishToMavenLocal will upload all the needed artifacts to the local Maven repository, which is a directory on the local machine. You can check the result in this directory, which is usually located in /Users/<user_name>/.m2 directory, or by connecting your library to the sample multiplatform project, for example, the KMM project, which could be easily created with the KMM plugin for Android Studio project wizard. Add a dependency on your locally published library in the shared module build.gradle.kts:

repositories {
    mavenLocal() 
}

kotlin {
    android()
    ios ()

    sourceSets {
        val commonMain by getting {
            dependencies {
              implementation("io.github.katerinapetrova:mpp-sample-lib:1.0.0")
            }
        }
    }
}

The best way to explore our new library structure is through the dependency section in the project tree:

Wow! 😱 There is a lot of stuff in here and I know you must be curious about it! So before going public, let's spend a little time looking at how our library is structured — check out the next part of the series 👀