Edit Page

Working with Kotlin/Native Libraries

Last Updated 22 January 2018
A look at how to work with Kotlin/Native libraries

In this tutorial we'll see

What is Kotlin/Native Library

The concept of a library, a collection of functions and other resources such as images, to be used by applications is available in Kotlin/Native and it is represented as a file with the extension klib. Kotlin/Native libraries are artifacts that are only available at compile time, i.e. we do not ship these as dependencies to our application (as we would for instance with DLL files on the Windows platform).

A klib file is a compressed archive in zip format with the following directory structure:

File utils.klib

    targets/                    /* One or more target platforms */
        macbook/                /* When targeting macbook, this entry would appear */
            kotlin/             /* Kotlin code compiled to LLVM bitcode */
            native/             /* Bitcode for additonal native objects */ 
        linux/                  /* When targeting Linux, this entry would appear */
    linkdata/                   /* A set of [ProtoBuf](https://github.com/google/protobuf) files with serialised linkage metadata */ 
    resources/                  /* Resource files such as images, etc. */

    manifest                    /* A file in Java Property Format describing the library */ 

Creating a Kotlin/Native Libraries

There are two ways we can create a Kotlin/Native library. The first and most common way is to use the Kotlin compiler. Let's assume we create a small library called utils.kt which contains the following two functions

package utils

fun printMessage(message: String) {
    println("Message: $message")

fun printWarning(warning: String) {
    println("Warning: $warning")

To create a library from this file, we can use the compiler with the parameter -produce library or -p library for short:

konanc utils.kt -p library

By default, the output of the filename is library.klib. We can override it using the -output or -o parameter:

konanc utils.kt -p library -o utils

The second way to create a library is using the cinterop tool which allows us to create a Kotlin/Native library from an existing C library. See the Interop with C tutorial on how to accomplish this.

Consuming a Kotlin/Native Library

Now that we have our library, we can use it in our application. In our case this is a simple file named sample.kt with the following contents:

import utils.*

fun main(args: Array<String>) {
    printWarning("App is about to shut down!")

Notice how we need to import the necessary package from the library on the first line using the import statement.

In order for the compiler to correctly link in the library, we need to pass the library name using the -library or -l parameter

konanc sample.kt -l utils

This would then produce a single executable file with no runtime dependencies.

Using and creating library repositories

Often it is useful to use the same library across multiple applications. To avoid having various copies of the same library, the Kotlin compiler can search for libraries in what's called a library repository. The default repository is usually installed under the folder ~/konanc/klib and we can add and remove our own libraries with a utility named klib that ships as part of the compiler tools.

Installing libraries to the default repository

The easiest way to install a library so that it can be later referenced by any application is to use klib with the following command:

klib install utils

This will copy and extract the necessary files to the proper locations in the default library folder, allowing us to then compile our application and link a specific library without needing to have the klib file in the project folder:

konanc sample.kt -l utils

We can of course also uninstall libraries at any point by issuing the command:

klib remove utils

Installing libraries to custom repositories

In addition to using the default repository, we can also have libraries stored in custom repositories, which can be useful for instance if we want to share libraries amongst a group of projects.

In order to do this, we can once again use the command klib:

klib install utils -repository jetbrains

but this time adding the parameter -repository with the value jetbrains. This installs the utils library into a custom repository located in a subdirecty named jetbrains relative to where we execute the command. For instance if our project is located under the directory /home/kotlin/projects/, the above command would install the library to the directory /home/kotlin/projects/jetbrains/utils.

For more information about the commands available for klib as well as the sequence when searching for libraries, please see the README