Kotlin/Native를 동적 라이브러리로 사용하기 – 튜토리얼

Kotlin 코드를 기존 프로그램에서 사용하기 위해 동적 라이브러리를 생성할 수 있습니다. 이를 통해 JVM, Python, Android 등을 포함한 다양한 플랫폼 또는 언어 간에 코드를 공유할 수 있습니다.

iOS 및 기타 Apple 대상의 경우 프레임워크 생성을 권장합니다. Kotlin/Native를 Apple 프레임워크로 사용하기 튜토리얼을 참조하세요.

기존 네이티브 애플리케이션 또는 라이브러리에서 Kotlin/Native 코드를 사용할 수 있습니다. 이를 위해 Kotlin 코드를 .so, .dylib, 또는 .dll 형식의 동적 라이브러리로 컴파일해야 합니다.

이 튜토리얼에서는 다음을 수행합니다.

Kotlin 코드를 동적 라이브러리로 컴파일합니다.
생성된 C 헤더를 살펴봅니다.
C에서 Kotlin 동적 라이브러리를 사용합니다.
프로젝트를 컴파일하고 실행합니다.

명령줄을 사용하거나 스크립트 파일(예: .sh 또는 .bat 파일)을 사용하여 직접 Kotlin 라이브러리를 생성할 수 있습니다. 하지만 이 접근 방식은 수백 개의 파일과 라이브러리를 가진 대규모 프로젝트에는 확장성이 떨어집니다. 빌드 시스템을 사용하면 Kotlin/Native 컴파일러 바이너리 및 전이적 종속성이 있는 라이브러리를 다운로드하고 캐싱하며, 컴파일러 및 테스트를 실행하여 프로세스를 간소화합니다. Kotlin/Native는 Kotlin Multiplatform 플러그인을 통해 Gradle 빌드 시스템을 사용할 수 있습니다.

Gradle을 사용한 고급 C 상호 운용성 관련 Kotlin/Native 및 Kotlin Multiplatform 빌드 사용법을 살펴보겠습니다.

Mac을 사용하고 macOS 또는 기타 Apple 대상을 위한 애플리케이션을 생성하고 실행하려는 경우, Xcode Command Line Tools를 설치하고 먼저 실행하여 라이선스 약관에 동의해야 합니다.

Kotlin 라이브러리 생성

Kotlin/Native 컴파일러는 Kotlin 코드로부터 동적 라이브러리를 생성할 수 있습니다. 동적 라이브러리에는 일반적으로 .h 헤더 파일이 함께 제공되며, 이를 사용하여 C에서 컴파일된 코드를 호출합니다.

Kotlin 라이브러리를 생성하고 C 프로그램에서 사용하는 방법을 살펴보겠습니다.

자세한 첫 단계 및 새 Kotlin/Native 프로젝트를 생성하고 IntelliJ IDEA에서 여는 방법에 대한 지침은 Kotlin/Native 시작하기 튜토리얼을 참조하세요.

src/nativeMain/kotlin 디렉터리로 이동하여 다음 라이브러리 내용이 포함된 lib.kt 파일을 생성합니다.

kotlin

package example
 
object Object { 
    val field = "A"
}
 
class Clazz {
    fun memberFunction(p: Int): ULong = 42UL
}
 
fun forIntegers(b: Byte, s: Short, i: UInt, l: Long) { }
fun forFloats(f: Float, d: Double) { }
 
fun strings(str: String) : String? {
    return "That is '$str' from C"
}
 
val globalString = "A global String"

다음 내용으로 build.gradle(.kts) Gradle 빌드 파일을 업데이트합니다.

KotlinGroovy

kotlin

plugins {
    kotlin("multiplatform") version "2.2.10"
}

repositories {
    mavenCentral()
}

kotlin {
    macosArm64("native") {    // macOS on Apple Silicon
    // macosX64("native") {   // macOS on x86_64 platforms
    // linuxArm64("native") { // Linux on ARM64 platforms
    // linuxX64("native") {   // Linux on x86_64 platforms
    // mingwX64("native") {   // Windows
        binaries {
            sharedLib {
                baseName = "native"       // macOS and Linux 
                // baseName = "libnative" // Windows
            }
        }
    }
}

tasks.wrapper {
    gradleVersion = "8.14"
    distributionType = Wrapper.DistributionType.ALL
}

groovy

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.2.10'
}

repositories {
    mavenCentral()

kotlin {
    macosArm64("native") {    // Apple Silicon macOS
    // macosX64("native") {   // macOS on x86_64 platforms
    // linuxArm64("native") { // Linux on ARM64 platforms
    // linuxX64("native") {   // Linux on x86_64 platforms
    // mingwX64("native") {   // Windows
        binaries {
            sharedLib {
                baseName = "native"       // macOS and Linux 
                // baseName = "libnative" // Windows
            }
        }
    }
}

wrapper {
    gradleVersion = "8.14"
    distributionType = "ALL"
}

binaries {} 블록은 동적 또는 공유 라이브러리를 생성하도록 프로젝트를 구성합니다.
libnative는 라이브러리 이름이자 생성된 헤더 파일 이름의 접두사로 사용됩니다. 또한 헤더 파일의 모든 선언에 접두사로 붙습니다.

IDE에서 linkDebugSharedNative Gradle 작업을 실행하거나 터미널에서 다음 콘솔 명령어를 사용하여 라이브러리를 빌드합니다.
bash
```
./gradlew linkDebugSharedNative
```

빌드하면 라이브러리가 다음 파일들과 함께 build/bin/native/debugShared 디렉터리에 생성됩니다.

macOS: libnative_api.h 및 libnative.dylib
Linux: libnative_api.h 및 libnative.so
Windows: libnative_api.h, libnative.def, 및 libnative.dll

linkNative Gradle 작업을 사용하여 라이브러리의 debug 및 release 변형을 모두 생성할 수도 있습니다.

Kotlin/Native 컴파일러는 모든 플랫폼에 대해 .h 파일을 생성하는 데 동일한 규칙을 사용합니다. Kotlin 라이브러리의 C API를 살펴보겠습니다.

생성된 헤더 파일

Kotlin/Native 선언이 C 함수에 어떻게 매핑되는지 살펴보겠습니다.

build/bin/native/debugShared 디렉터리에서 libnative_api.h 헤더 파일을 엽니다. 가장 첫 부분에는 표준 C/C++ 헤더와 푸터가 포함됩니다.

#ifndef KONAN_LIBNATIVE_H
#define KONAN_LIBNATIVE_H
#ifdef __cplusplus
extern "C" {
#endif

/// The rest of the generated code

#ifdef __cplusplus
}  /* extern "C" */
#endif
#endif  /* KONAN_LIBNATIVE_H */

이어서 libnative_api.h에는 공통 타입 정의 블록이 포함됩니다.

#ifdef __cplusplus
typedef bool            libnative_KBoolean;
#else
typedef _Bool           libnative_KBoolean;
#endif
typedef unsigned short     libnative_KChar;
typedef signed char        libnative_KByte;
typedef short              libnative_KShort;
typedef int                libnative_KInt;
typedef long long          libnative_KLong;
typedef unsigned char      libnative_KUByte;
typedef unsigned short     libnative_KUShort;
typedef unsigned int       libnative_KUInt;
typedef unsigned long long libnative_KULong;
typedef float              libnative_KFloat;
typedef double             libnative_KDouble;
typedef float __attribute__ ((__vector_size__ (16))) libnative_KVector128;
typedef void*              libnative_KNativePtr;

Kotlin은 생성된 libnative_api.h 파일의 모든 선언에 libnative_ 접두사를 사용합니다. 다음은 타입 매핑의 전체 목록입니다.

Kotlin 정의	C 타입
`libnative_KBoolean`	`bool` or `_Bool`
`libnative_KChar`	`unsigned short`
`libnative_KByte`	`signed char`
`libnative_KShort`	`short`
`libnative_KInt`	`int`
`libnative_KLong`	`long long`
`libnative_KUByte`	`unsigned char`
`libnative_KUShort`	`unsigned short`
`libnative_KUInt`	`unsigned int`
`libnative_KULong`	`unsigned long long`
`libnative_KFloat`	`float`
`libnative_KDouble`	`double`
`libnative_KVector128`	`float __attribute__ ((__vector_size__ (16))`
`libnative_KNativePtr`	`void*`

libnative_api.h 파일의 정의 섹션은 Kotlin 프리미티브 타입이 C 프리미티브 타입에 어떻게 매핑되는지를 보여줍니다. Kotlin/Native 컴파일러는 모든 라이브러리에 대해 이러한 항목을 자동으로 생성합니다. 역방향 매핑은 C에서 프리미티브 데이터 타입 매핑 튜토리얼에 설명되어 있습니다.

자동으로 생성된 타입 정의 다음에는 라이브러리에서 사용되는 별도의 타입 정의가 있습니다.

struct libnative_KType;
typedef struct libnative_KType libnative_KType;

/// Automatically generated type definitions

typedef struct {
  libnative_KNativePtr pinned;
} libnative_kref_example_Object;
typedef struct {
  libnative_KNativePtr pinned;
} libnative_kref_example_Clazz;

C에서 typedef struct { ... } TYPE_NAME 구문은 구조체를 선언합니다.

이 패턴에 대한 자세한 설명은 이 StackOverflow 스레드를 참조하세요.

이러한 정의에서 알 수 있듯이, Kotlin 타입은 동일한 패턴을 사용하여 매핑됩니다. Object는 libnative_kref_example_Object에 매핑되고, Clazz는 libnative_kref_example_Clazz에 매핑됩니다. 모든 구조체는 포인터가 있는 pinned 필드 외에는 아무것도 포함하지 않습니다. libnative_KNativePtr 필드 타입은 파일의 앞부분에서 void*로 정의됩니다.

C는 네임스페이스를 지원하지 않기 때문에, Kotlin/Native 컴파일러는 기존 네이티브 프로젝트의 다른 심볼과 충돌할 가능성을 피하기 위해 긴 이름을 생성합니다.

서비스 런타임 함수

libnative_ExportedSymbols 구조체는 Kotlin/Native와 라이브러리에서 제공하는 모든 함수를 정의합니다. 패키지를 모방하기 위해 중첩된 익명 구조체를 많이 사용합니다. libnative_ 접두사는 라이브러리 이름에서 가져온 것입니다.

libnative_ExportedSymbols는 헤더 파일에 여러 헬퍼 함수를 포함합니다.

typedef struct {
  /* Service functions. */
  void (*DisposeStablePointer)(libnative_KNativePtr ptr);
  void (*DisposeString)(const char* string);

이 함수들은 Kotlin/Native 객체를 처리합니다. DisposeStablePointer는 Kotlin 객체에 대한 참조를 해제하는 데 사용되며, DisposeString은 C에서 char* 타입인 Kotlin 문자열을 해제하는 데 사용됩니다.

libnative_api.h 파일의 다음 부분은 런타임 함수의 구조체 선언으로 구성됩니다.

libnative_KBoolean (*IsInstance)(libnative_KNativePtr ref, const libnative_KType* type);
libnative_KBoolean (*IsInstance)(libnative_KNativePtr ref, const libnative_KType* type);
libnative_kref_kotlin_Byte (*createNullableByte)(libnative_KByte);
libnative_KByte (*getNonNullValueOfByte)(libnative_kref_kotlin_Byte);
libnative_kref_kotlin_Short (*createNullableShort)(libnative_KShort);
libnative_KShort (*getNonNullValueOfShort)(libnative_kref_kotlin_Short);
libnative_kref_kotlin_Int (*createNullableInt)(libnative_KInt);
libnative_KInt (*getNonNullValueOfInt)(libnative_kref_kotlin_Int);
libnative_kref_kotlin_Long (*createNullableLong)(libnative_KLong);
libnative_KLong (*getNonNullValueOfLong)(libnative_kref_kotlin_Long);
libnative_kref_kotlin_Float (*createNullableFloat)(libnative_KFloat);
libnative_KFloat (*getNonNullValueOfFloat)(libnative_kref_kotlin_Float);
libnative_kref_kotlin_Double (*createNullableDouble)(libnative_KDouble);
libnative_KDouble (*getNonNullValueOfDouble)(libnative_kref_kotlin_Double);
libnative_kref_kotlin_Char (*createNullableChar)(libnative_KChar);
libnative_KChar (*getNonNullValueOfChar)(libnative_kref_kotlin_Char);
libnative_kref_kotlin_Boolean (*createNullableBoolean)(libnative_KBoolean);
libnative_KBoolean (*getNonNullValueOfBoolean)(libnative_kref_kotlin_Boolean);
libnative_kref_kotlin_Unit (*createNullableUnit)(void);
libnative_kref_kotlin_UByte (*createNullableUByte)(libnative_KUByte);
libnative_KUByte (*getNonNullValueOfUByte)(libnative_kref_kotlin_UByte);
libnative_kref_kotlin_UShort (*createNullableUShort)(libnative_KUShort);
libnative_KUShort (*getNonNullValueOfUShort)(libnative_kref_kotlin_UShort);
libnative_kref_kotlin_UInt (*createNullableUInt)(libnative_KUInt);
libnative_KUInt (*getNonNullValueOfUInt)(libnative_kref_kotlin_UInt);
libnative_kref_kotlin_ULong (*createNullableULong)(libnative_KULong);
libnative_KULong (*getNonNullValueOfULong)(libnative_kref_kotlin_ULong);

IsInstance 함수를 사용하여 Kotlin 객체(.pinned 포인터로 참조됨)가 특정 타입의 인스턴스인지 확인할 수 있습니다. 생성되는 실제 연산 집합은 실제 사용법에 따라 달라집니다.

Kotlin/Native는 자체 가비지 컬렉터를 가지고 있지만, C에서 접근하는 Kotlin 객체를 관리하지 않습니다. 하지만 Kotlin/Native는 Swift/Objective-C와의 상호 운용성을 제공하며, 가비지 컬렉터는 Swift/Objective-C ARC와 통합됩니다.

라이브러리 함수

라이브러리에서 사용되는 별도의 구조체 선언을 살펴보겠습니다. libnative_kref_example 필드는 libnative_kref. 접두사를 사용하여 Kotlin 코드의 패키지 구조를 모방합니다.

typedef struct {
  /* User functions. */
  struct {
    struct {
      struct {
        struct {
          libnative_KType* (*_type)(void);
          libnative_kref_example_Object (*_instance)();
          const char* (*get_field)(libnative_kref_example_Object thiz);
        } Object;
        struct {
          libnative_KType* (*_type)(void);
          libnative_kref_example_Clazz (*Clazz)();
          libnative_KULong (*memberFunction)(libnative_kref_example_Clazz thiz, libnative_KInt p);
        } Clazz;
        const char* (*get_globalString)();
        void (*forFloats)(libnative_KFloat f, libnative_KDouble d);
        void (*forIntegers)(libnative_KByte b, libnative_KShort s, libnative_KUInt i, libnative_KLong l);
        const char* (*strings)(const char* str);
      } example;
    } root;
  } kotlin;
} libnative_ExportedSymbols;

이 코드는 익명 구조체 선언을 사용합니다. 여기서 struct { ... } foo는 이름이 없는 익명 구조체 타입의 바깥 구조체에 필드를 선언합니다.

C 또한 객체를 지원하지 않기 때문에, 함수 포인터를 사용하여 객체 의미론을 모방합니다. 함수 포인터는 RETURN_TYPE (* FIELD_NAME)(PARAMETERS)와 같이 선언됩니다.

libnative_kref_example_Clazz 필드는 Kotlin의 Clazz를 나타냅니다. libnative_KULong은 memberFunction 필드를 통해 접근할 수 있습니다. 유일한 차이점은 memberFunction이 첫 번째 파라미터로 thiz 참조를 받는다는 것입니다. C는 객체를 지원하지 않으므로, thiz 포인터는 명시적으로 전달됩니다.

Clazz 필드(일명 libnative_kref_example_Clazz_Clazz)에는 Clazz의 인스턴스를 생성하는 생성자 함수 역할을 하는 생성자가 있습니다.

Kotlin object Object는 libnative_kref_example_Object로 접근할 수 있습니다. _instance 함수는 해당 객체의 유일한 인스턴스를 검색합니다.

속성은 함수로 변환됩니다. get_ 및 set_ 접두사는 각각 getter 및 setter 함수의 이름을 지정합니다. 예를 들어, Kotlin의 읽기 전용 속성 globalString은 C에서 get_globalString 함수로 변환됩니다.

전역 함수 forFloats, forIntegers, strings는 libnative_kref_example 익명 구조체 내의 함수 포인터로 변환됩니다.

진입점

이제 API가 어떻게 생성되는지 알았으니, libnative_ExportedSymbols 구조체의 초기화가 시작점입니다. 그럼 libnative_api.h의 마지막 부분을 살펴보겠습니다.

extern libnative_ExportedSymbols* libnative_symbols(void);

libnative_symbols 함수를 사용하면 네이티브 코드에서 Kotlin/Native 라이브러리로의 게이트웨이를 열 수 있습니다. 이는 라이브러리에 접근하기 위한 진입점입니다. 라이브러리 이름은 함수 이름의 접두사로 사용됩니다.

반환된 libnative_ExportedSymbols* 포인터를 스레드별로 호스팅해야 할 수도 있습니다.

C에서 생성된 헤더 사용

C에서 생성된 헤더를 사용하는 것은 간단합니다. 라이브러리 디렉터리에 다음 코드가 포함된 main.c 파일을 생성합니다.

#include "libnative_api.h"
#include "stdio.h"

int main(int argc, char** argv) {
  // Obtain reference for calling Kotlin/Native functions
  libnative_ExportedSymbols* lib = libnative_symbols();

  lib->kotlin.root.example.forIntegers(1, 2, 3, 4);
  lib->kotlin.root.example.forFloats(1.0f, 2.0);

  // Use C and Kotlin/Native strings
  const char* str = "Hello from Native!";
  const char* response = lib->kotlin.root.example.strings(str);
  printf("in: %s
out:%s
", str, response);
  lib->DisposeString(response);

  // Create Kotlin object instance
  libnative_kref_example_Clazz newInstance = lib->kotlin.root.example.Clazz.Clazz();
  long x = lib->kotlin.root.example.Clazz.memberFunction(newInstance, 42);
  lib->DisposeStablePointer(newInstance.pinned);

  printf("DemoClazz returned %ld
", x);

  return 0;
}

프로젝트 컴파일 및 실행

macOS에서

C 코드를 컴파일하고 동적 라이브러리와 링크하려면 라이브러리 디렉터리로 이동하여 다음 명령어를 실행합니다.

bash

clang main.c libnative.dylib

컴파일러는 a.out이라는 실행 파일을 생성합니다. 이를 실행하여 C 라이브러리에서 Kotlin 코드를 실행합니다.

Linux에서

C 코드를 컴파일하고 동적 라이브러리와 링크하려면 라이브러리 디렉터리로 이동하여 다음 명령어를 실행합니다.

bash

gcc main.c libnative.so

컴파일러는 a.out이라는 실행 파일을 생성합니다. 이를 실행하여 C 라이브러리에서 Kotlin 코드를 실행합니다. Linux에서는 애플리케이션이 현재 폴더에서 libnative.so 라이브러리를 로드하도록 LD_LIBRARY_PATH에 .을 포함해야 합니다.

Windows에서

먼저 x64_64 대상을 지원하는 Microsoft Visual C++ 컴파일러를 설치해야 합니다.

가장 쉬운 방법은 Windows 컴퓨터에 Microsoft Visual Studio를 설치하는 것입니다. 설치 중에 C++ 작업을 위한 필수 구성 요소(예: C++를 사용한 데스크톱 개발)를 선택합니다.

Windows에서는 정적 라이브러리 래퍼를 생성하거나 LoadLibrary 또는 유사한 Win32API 함수를 사용하여 수동으로 동적 라이브러리를 포함할 수 있습니다.

첫 번째 옵션을 사용하여 libnative.dll에 대한 정적 래퍼 라이브러리를 생성해 보겠습니다.

도구 체인에서 lib.exe를 호출하여 코드에서 DLL 사용을 자동화하는 정적 라이브러리 래퍼 libnative.lib를 생성합니다.
bash
```
lib /def:libnative.def /out:libnative.lib
```
main.c를 실행 파일로 컴파일합니다. 생성된 libnative.lib를 빌드 명령에 포함하고 시작합니다.
bash
```
cl.exe main.c libnative.lib
```
이 명령은 실행할 수 있는 main.exe 파일을 생성합니다.

기본 타입

빌더

Spring

Spring Boot를 사용하여 데이터베이스와 RESTful 웹 서비스 만들기

Java에서 Kotlin으로 마이그레이션 가이드

C 상호 운용

Objective-C 상호 운용

메모리 관리자

참조 및 팁

JS 플랫폼을 위한 Kotlin

Gradle

Dokka 실행

출력 형식

인지 복잡성 최소화

Kotlin/Native를 동적 라이브러리로 사용하기 – 튜토리얼

Kotlin 라이브러리 생성

생성된 헤더 파일

서비스 런타임 함수

라이브러리 함수

진입점

C에서 생성된 헤더 사용

프로젝트 컴파일 및 실행

macOS에서

Linux에서

Windows에서

다음 단계

Spring Boot를 사용하여 데이터베이스와 RESTful 웹 서비스 만들기

Kotlin/Native를 동적 라이브러리로 사용하기 – 튜토리얼 ​

Kotlin 라이브러리 생성 ​

생성된 헤더 파일 ​

서비스 런타임 함수 ​

라이브러리 함수 ​

진입점 ​

C에서 생성된 헤더 사용 ​

프로젝트 컴파일 및 실행 ​

macOS에서 ​

Linux에서 ​

Windows에서 ​

다음 단계 ​

Kotlin/Native를 동적 라이브러리로 사용하기 – 튜토리얼

Kotlin 라이브러리 생성

생성된 헤더 파일

서비스 런타임 함수

라이브러리 함수

진입점

C에서 생성된 헤더 사용

프로젝트 컴파일 및 실행

macOS에서

Linux에서

Windows에서

다음 단계