Using C Interop and libcurl for an app – tutorial
When writing native applications, oftentimes you need to access certain functionality that is not included in the Kotlin standard library, such as making HTTP requests, reading and writing from disk, etc.
Kotlin/Native provides you with the ability to consume standard C libraries, opening up an entire ecosystem of functionality that exists for pretty much anything you could need. In fact, Kotlin/Native already ships with a set of prebuilt platform libraries which provide some additional common functionality to that of the standard library.
In this tutorial, you'll see how to use some specific libraries, such as
libcurl. You'll learn to:
An ideal scenario for interop is to call C functions as if you were calling Kotlin functions, that is, following the same signature and conventions. This is precisely what the
cinterop tool provides. It takes a C library and generates the corresponding Kotlin bindings for it, which then allows you to use the library as if it were Kotlin code.
In order to generate these bindings, you need to create a library definition
.def file that contains some information about the headers you need to generate. In this case, you'll use the famous
libcurl library to make some HTTP calls, so create a file named
libcurl.def with the following contents:
A few things are going on in this file, let's go through them one by one. The first entry is
headers which is the list of header files that you want to generate Kotlin stubs for. You can add multiple files to this entry, separating each one with a
\ on a new line. For this tutorial, you'll only need
curl.h. The files we are referencing need to be relative to the folder where the definition file is, or be available on the system path (
The second line is the
headerFilter. This is used to denote what exactly we want included. In C, when one file references another file with the
#include directive, all the headers are also included. Sometimes this may not be needed, and you can use this parameter, using glob patterns, to fine tune things. Note, that
headerFilter is an optional argument and mostly only used when the library you're using is being installed as a system library, and you do not want to fetch external dependencies (such as system
stdint.h header) into your interop library. It may be important for both optimizing the library size and fixing potential conflicts between the system and the Kotlin/Native provided compilation environment.
The next lines are about providing linker and compiler options, which can vary depending on different target platforms. In this tutorial, we are defining it for macOS (the
.osx suffix) and Linux (the
.linux suffix). Parameters without a suffix is also possible (e.g.
linkerOpts=) and will be applied to all platforms.
The convention that is followed is that each library gets its own definition file, usually named the same as the library. For more information on all the options available to
cinterop, see the Interop documentation
Once you have the definition file ready, create project files and open the project in an IDE.
While it is possible to use the command line, either directly or by combining it with a script file (such as
.bat file), this approach doesn't scale well for big projects that have hundreds of files and libraries. It is then better to use the Kotlin/Native compiler with a build system, as it helps to download and cache the Kotlin/Native compiler binaries and libraries with transitive dependencies and run the compiler and tests. Kotlin/Native can use the Gradle build system through the kotlin-multiplatform plugin.
We covered the basics of setting up an IDE compatible project with Gradle in the A Basic Kotlin/Native Application tutorial. Please check it out if you are looking for detailed first steps and instructions on how to start a new Kotlin/Native project and open it in IntelliJ IDEA. In this tutorial, we'll look at the advanced C interop related usages of Kotlin/Native and multiplatform builds with Gradle.
First, create a project folder. All the paths in this tutorial will be relative to this folder. Sometimes the missing directories will have to be created before any new files can be added.
Use the following
build.gradle(.kts) Gradle build file:
The project file configures the C interop as an additional step of the build. Let's move the
interop.def file to the
src/nativeInterop/cinterop directory. Gradle recommends using conventions instead of configurations, for example, the source files are expected to be in the
src/nativeMain/kotlin folder. By default, all the symbols from C are imported to the
interop package, you may want to import the whole package in our
.kt files. Check out the kotlin-multiplatform plugin documentation to learn about all the different ways you could configure it.
curl on Windows
You should have the
curl library binaries on Windows to make the sample work. You may build
curl from sources on Windows (you'll need Visual Studio or Windows SDK Commandline tools), for more details, see the related blog post. Alternatively, you may also want to consider a MinGW/MSYS2
Consume the Kotlin API
Now you have the library and Kotlin stubs and can consume them from our application. To keep things simple, in this tutorial you're going to convert one of the simplest
libcurl examples over to Kotlin.
The code in question is from the simple example (comments removed for brevity):
The first thing you'll need is a Kotlin file called
src/nativeMain/kotlin/hello.kt with the
main function defined in it and then proceed to translate each line.
As you can see, you've eliminated the explicit variable declarations in the Kotlin version, but everything else is pretty much verbatim to the C version. All the calls you'd expect in the
libcurl library are available in their Kotlin equivalent.
Note that for the purpose of this tutorial, we've done a line by line literal translation. Obviously you could write this in a more Kotlin idiomatic way.
Compile and link the library
The next step is to compile the application. We already covered the basics of compiling a Kotlin/Native application from the command line in the A Basic Kotlin/Native application tutorial. The only difference in this case is that the
cinterop generated part is implicitly included into the build: Call the following command:
If there are no errors during compilation, you should see the result of the execution of the program, which on execution should output the contents of the site
The reason you're seeing the actual output is because the call
curl_easy_perform prints the result to the standard output. You could hide this using
For a more complete example of using
libcurl, the libcurl sample of the Kotlin/Native project shows how to abstract the code into Kotlin classes as well as display headers. It also demonstrates how to make the steps a little easier by combining them into a shell script or Gradle build.