Kotlin/Native as an Apple framework – tutorial

tip

See the Get started with Kotlin/Native tutorial for detailed first steps and instructions on how to create a new Kotlin/Native project and open it in IntelliJ IDEA.

The Kotlin/Native compiler can produce a framework for macOS and iOS from the Kotlin code. The created framework contains all declarations and binaries needed to use it with Swift/Objective-C.

Let's first create a Kotlin library:

1. In the src/nativeMain/kotlin directory, create the lib.kt file with the library contents:

   package example
   
   object Object {
       val field = "A"
   }
   
   interface Interface {
       fun iMember() {}
   }
   
   class Clazz : Interface {
       fun member(p: Int): ULong? = 42UL
   }
   
   fun forIntegers(b: Byte, s: UShort, i: Int, l: ULong?) { }
   fun forFloats(f: Float, d: Double?) { }
   
   fun strings(str: String?) : String {
       return "That is '$str' from C"
   }
   
   fun acceptFun(f: (String) -> String?) = f("Kotlin/Native rocks!")
   fun supplyFun() : (String) -> String? = { "$it is cool!" }

2. Update your build.gradle(.kts) Gradle build file with the following:

   Kotlin

   Groovy

   plugins {
       kotlin("multiplatform") version "2.1.20"
   }
   
   repositories {
       mavenCentral()
   }
   
   kotlin {
       iosArm64("native") {
           binaries {
               framework {
                   baseName = "Demo"
               }
           }
       }
   }
   
   tasks.wrapper {
       gradleVersion = "8.10"
       distributionType = Wrapper.DistributionType.ALL
   }

   plugins {
       id 'org.jetbrains.kotlin.multiplatform' version '2.1.20'
   }
   
   repositories {
       mavenCentral()
   }
   
   kotlin {
       iosArm64("native") {
           binaries {
               framework {
                   baseName = "Demo"
               }
           }
       }
   }
   
   wrapper {
       gradleVersion = "8.10"
       distributionType = "ALL"
   }

   The binaries {} block configures the project to generate a dynamic or shared library.

   Kotlin/Native supports the iosArm64, iosX64, and iosSimulatorArm64 targets for iOS, as well as macosX64 and macosArm64 targets for macOS. So, you can replace the iosArm64() with the respective Gradle function for your target platform:

   Target platform/device	Gradle function
   macOS x86_64	macosX64()
   macOS ARM64	macosArm64()
   iOS ARM64	iosArm64()
   iOS Simulator (x86_64)	iosX64()
   iOS Simulator (ARM64)	iosSimulatorArm64()

   For information on other supported Apple targets, see Kotlin/Native target support.

3. Run the linkDebugFrameworkNative Gradle task in the IDE or use the following console command in your terminal to build the framework:

   ./gradlew linkDebugFrameworkNative

The build generates the framework into the build/bin/native/debugFramework directory.

tip

You can also use the linkNative Gradle task to generate both debug and release variants of the framework.

Each framework variant contains a header file. The headers don't depend on the target platform. Header files contain definitions for your Kotlin code and a few Kotlin-wide declarations. Let's see what's inside.

NS_ASSUME_NONNULL_BEGIN
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wunknown-warning-option"
#pragma clang diagnostic ignored "-Wincompatible-property-type"
#pragma clang diagnostic ignored "-Wnullability"

#pragma push_macro("_Nullable_result")
#if !__has_feature(nullability_nullable_result)
#undef _Nullable_result
#define _Nullable_result _Nullable
#endif

__attribute__((swift_name("KotlinBase")))
@interface DemoBase : NSObject
- (instancetype)init __attribute__((unavailable));
+ (instancetype)new __attribute__((unavailable));
+ (void)initialize __attribute__((objc_requires_super));
@end

@interface DemoBase (DemoBaseCopying) <NSCopying>
@end

__attribute__((swift_name("KotlinMutableSet")))
@interface DemoMutableSet<ObjectType> : NSMutableSet<ObjectType>
@end

__attribute__((swift_name("KotlinMutableDictionary")))
@interface DemoMutableDictionary<KeyType, ObjectType> : NSMutableDictionary<KeyType, ObjectType>
@end

@interface NSError (NSErrorDemoKotlinException)
@property (readonly) id _Nullable kotlinException;
@end

__attribute__((swift_name("Kotlin__TYPE__")))
@interface Demo__TYPE__ : DemoNumber
- (instancetype)initWith__TYPE__:(__CTYPE__)value;
+ (instancetype)numberWith__TYPE__:(__CTYPE__)value;
@end;

__attribute__((swift_name("Interface")))
@protocol DemoInterface
@required
- (void)iMember __attribute__((swift_name("iMember()")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Clazz")))
@interface DemoClazz : DemoBase <DemoInterface>
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
- (DemoULong * _Nullable)memberP:(int32_t)p __attribute__((swift_name("member(p:)")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Object")))
@interface DemoObject : DemoBase
+ (instancetype)alloc __attribute__((unavailable));
+ (instancetype)allocWithZone:(struct _NSZone *)zone __attribute__((unavailable));
+ (instancetype)object __attribute__((swift_name("init()")));
@property (class, readonly, getter=shared) DemoObject *shared __attribute__((swift_name("shared")));
@property (readonly) NSString *field __attribute__((swift_name("field")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("LibKt")))
@interface DemoLibKt : DemoBase
+ (NSString * _Nullable)acceptFunF:(NSString * _Nullable (^)(NSString *))f __attribute__((swift_name("acceptFun(f:)")));
+ (void)forFloatsF:(float)f d:(DemoDouble * _Nullable)d __attribute__((swift_name("forFloats(f:d:)")));
+ (void)forIntegersB:(int8_t)b s:(uint16_t)s i:(int32_t)i l:(DemoULong * _Nullable)l __attribute__((swift_name("forIntegers(b:s:i:l:)")));
+ (NSString *)stringsStr:(NSString * _Nullable)str __attribute__((swift_name("strings(str:)")));
+ (NSString * _Nullable (^)(NSString *))supplyFun __attribute__((swift_name("supplyFun()")));
@end

Swift and Objective-C use automatic reference counting (ARC). Kotlin/Native has its own garbage collector, which is also integrated with Objective-C/Swift ARC.

Unused Kotlin objects are automatically removed. You don't need to take additional steps to control the lifetime of Kotlin/Native instances from Swift or Objective-C.

Let's call the framework from Objective-C. In the framework directory, create the main.m file with the following code:

#import <Foundation/Foundation.h>
#import <Demo/Demo.h>

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        [DemoObject.shared field];

        DemoClazz* clazz = [[ DemoClazz alloc] init];
        [clazz memberP:42];

        [DemoLibKt forIntegersB:1 s:1 i:3 l:[DemoULong numberWithUnsignedLongLong:4]];
        [DemoLibKt forIntegersB:1 s:1 i:3 l:nil];

        [DemoLibKt forFloatsF:2.71 d:[DemoDouble numberWithDouble:2.71]];
        [DemoLibKt forFloatsF:2.71 d:nil];

        NSString* ret = [DemoLibKt acceptFunF:^NSString * _Nullable(NSString * it) {
            return [it stringByAppendingString:@" Kotlin is fun"];
        }];

        NSLog(@"%@", ret);
        return 0;
    }
}

Here, you call Kotlin classes directly from Objective-C code. A Kotlin object uses the <object name>.shared class property, which allows you to get the object's only instance and call object methods on it.

The widespread pattern is used to create an instance of the Clazz class. You call the [[ DemoClazz alloc] init] on Objective-C. You can also use [DemoClazz new] for constructors without parameters.

Global declarations from the Kotlin sources are scoped under the DemoLibKt class in Objective-C. All Kotlin functions are turned into class methods of that class.

The strings function is turned into DemoLibKt.stringsStr function in Objective-C, so you can pass NSString directly to it. The return value is visible as NSString too.

The framework you generated has helper attributes to make it easier to use with Swift. Let's convert the previous Objective-C example into Swift.

In the framework directory, create the main.swift file with the following code:

import Foundation
import Demo

let kotlinObject = Object.shared

let field = Object.shared.field

let clazz = Clazz()
clazz.member(p: 42)

LibKt.forIntegers(b: 1, s: 2, i: 3, l: 4)
LibKt.forFloats(f: 2.71, d: nil)

let ret = LibKt.acceptFun { "\($0) Kotlin is fun" }
if (ret != nil) {
    print(ret!)
}

There are some small differences between the original Kotlin code and its Swift version. In Kotlin, any object declaration has only one instance. The Object.shared syntax is used to access this single instance.

Kotlin function and property names are translated as is. Kotlin's String is turned into Swift's String. Swift hides NSNumber* boxing too. You can also pass a Swift closure to Kotlin and call a Kotlin lambda function from Swift.

You can find more information about type mapping in Interoperability with Swift/Objective-C.

Now you can connect the generated framework to your iOS project as a dependency. There are multiple ways to set it up and automate the process, choose the method that suits you best:

• Learn more about interoperability with Objective-C

• See how interoperability with C is implemented in Kotlin

• Check out the Kotlin/Native as a dynamic library tutorial