Kotlin/Native libraries

Edit pageLast modified: 25 September 2024

Kotlin compiler specifics

To produce a library with the Kotlin/Native compiler use the -produce library or -p library flag. For example:

$ kotlinc-native foo.kt -p library -o bar

This command will produce a bar.klib with the compiled contents of foo.kt.

To link to a library use the -library <name> or -l <name> flag. For example:

$ kotlinc-native qux.kt -l bar

This command will produce a program.kexe out of qux.kt and bar.klib

cinterop tool specifics

The cinterop tool produces .klib wrappers for native libraries as its main output. For example, using the simple libgit2.def native library definition file provided in your Kotlin/Native distribution

$ cinterop -def samples/gitchurn/src/nativeInterop/cinterop/libgit2.def -compiler-option -I/usr/local/include -o libgit2

we will obtain libgit2.klib.

See more details in C Interop.

klib utility

The klib library management utility allows you to inspect and install the libraries.

The following commands are available:

  • content – list library contents:

    $ klib contents <name>

  • info – inspect the bookkeeping details of the library

    $ klib info <name>

  • install – install the library to the default location use

    $ klib install <name>

  • remove – remove the library from the default repository use

    $ klib remove <name>

All of the above commands accept an additional -repository <directory> argument for specifying a repository different to the default one.

$ klib <command> <name> -repository <directory>

Several examples

First let's create a library. Place the tiny library source code into kotlinizer.kt:

package kotlinizer
val String.kotlinized
    get() = "Kotlin $this"
$ kotlinc-native kotlinizer.kt -p library -o kotlinizer

The library has been created in the current directory:

$ ls kotlinizer.klib
kotlinizer.klib

Now let's check out the contents of the library:

$ klib contents kotlinizer

You can install kotlinizer to the default repository:

$ klib install kotlinizer

Remove any traces of it from the current directory:

$ rm kotlinizer.klib

Create a very short program and place it into a use.kt:

import kotlinizer.*

fun main(args: Array<String>) {
    println("Hello, ${"world".kotlinized}!")
}

Now compile the program linking with the library you have just created:

$ kotlinc-native use.kt -l kotlinizer -o kohello

And run the program:

$ ./kohello.kexe
Hello, Kotlin world!

Have fun!

Advanced topics

Library search sequence

When given a -library foo flag, the compiler searches the foo library in the following order:

  • Current compilation directory or an absolute path.

  • All repositories specified with -repo flag.

  • Libraries installed in the default repository.

    note

    The default repository is ~/.konan. You can change it by setting the kotlin.data.dir Gradle property.

    Alternatively, you can use the -Xkonan-data-dir compiler option to configure your custom path to the directory via the cinterop and konanc tools.

  • Libraries installed in $installation/klib directory.

Library format

Kotlin/Native libraries are zip files containing a predefined directory structure, with the following layout:

foo.klib when unpacked as foo/ gives us:

- foo/
  - $component_name/
    - ir/
      - Serialized Kotlin IR.
    - targets/
      - $platform/
        - kotlin/
          - Kotlin compiled to LLVM bitcode.
        - native/
          - Bitcode files of additional native objects.
      - $another_platform/
        - There can be several platform specific kotlin and native pairs.
    - linkdata/
      - A set of ProtoBuf files with serialized linkage metadata.
    - resources/
      - General resources such as images. (Not used yet).
    - manifest - A file in the java property format describing the library.

An example layout can be found in klib/stdlib directory of your installation.

Using relative paths in klibs

note

Using relative paths in klibs is available since Kotlin 1.6.20.

A serialized IR representation of source files is a part of a klib library. It includes paths of files for generating proper debug information. By default, stored paths are absolute. With the -Xklib-relative-path-base compiler option, you can change the format and use only relative path in the artifact. To make it work, pass one or multiple base paths of source files as an argument:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    // $base is a base path of source files
    compilerOptions.freeCompilerArgs.add("-Xklib-relative-path-base=$base")
}