SuperAPI AI Directory

kotlin-multiplatform-native-authoring

Coding & development

View repository

Updated 11-17 16:30

About this skill

When to Use This Skill

Use this skill when you need to:

  • Write brand-new C/C++ source for a KMP library's native core — a custom renderer (Vulkan, Metal), a custom codec, a custom compute engine — where the code doesn't exist anywhere yet
  • Decide the directory layout, build system, and public header shape for that native core before any Kotlin binding is written
  • Set up native-side tests (ctest/gtest) independent of the Kotlin test suite

Do NOT use this skill when:

  • A 3rd-party C/C++ library already exists and needs a Kotlin bridge — that's kotlin-multiplatform-jni-pro's Phase 0 (library-first discovery); this skill's whole premise is that the native code doesn't exist yet
  • The task is writing the actual JNI/cinterop glue for native code that's already built — that's kotlin-multiplatform-jni-pro, always the next skill after this one, never a replacement for it
  • The native need is trivial (a handful of pure functions with no state, no build complexity) — a plain expect/actual Kotlin/Native implementation via kotlin-multiplatform-expect-actual may cover it without a separate C/C++ core at all

Trigger keywords: native core, first-party native code, author C++ library, CMakeLists.txt, native renderer, custom engine, native library scaffold, public C-ABI header, cinterop def file, native ctest, write native code from scratch.

Freshness rule: CMake, Android NDK toolchain versions, and Kotlin/Native cinterop all move independently of each other — recheck the current NDK version pinned in the project's local.properties/libs.versions.toml and the current Kotlin/Native cinterop docs before scaffolding; do not assume last year's CMake minimum version or .def file shape still applies.


Recommendation First

Default to this approach:

  1. One native/ directory, one CMakeLists.txt, reused across every platform — Android NDK, iOS/Kotlin-Native cinterop, and JVM/Desktop JNI all build from the same CMake project. Never duplicate build logic per platform.
  2. A stable public C-ABI header before any Kotlin code exists. native/include/ is the contract; native/src/ is free to change internally as long as the header doesn't. This header is exactly what kotlin-multiplatform-jni-pro's Phase 0 discovery will read once bridging starts.
  3. Plain C types at the actual boundary, even if internals are C++. STL containers, exceptions, and templates don't cross a JNI/cinterop boundary reliably — the public header speaks structs/primitives/opaque handles; C++ classes stay internal to native/src/.
  4. Native tests run independently, via ctest, in their own CI job — not bundled into the Kotlin jvmTest task, and not skipped because "the Kotlin side has tests."

Why:

  • one CMake project avoids the classic drift where Android's build flags silently diverge from iOS's for the same source
  • a stable header lets Kotlin-side work (this skill's output feeds directly into kotlin-multiplatform-jni-pro) start before every native feature is finished
  • a C-ABI boundary is the only boundary JNI and Kotlin/Native cinterop both actually support without extra shimming — designing for it from day one avoids an expensive C-shim retrofit later

Step 1: Directory layout

native/
├── CMakeLists.txt
├── include/
│   └── <library>/
│       └── <library>.h        # public C-ABI surface — the only file jni-pro reads
├── src/
│   ├── <library>.cpp           # C-ABI entry points, thin — delegates to internals below
│   └── internal/
│       └── ...                 # real C++ implementation, STL/exceptions/templates OK here
└── tests/
    ├── CMakeLists.txt
    └── <library>_test.cpp      # gtest/Catch2, native-only, no JVM/Kotlin involved

Rules:

  • include/ is the only directory kotlin-multiplatform-jni-pro's Phase 0 discovery should ever need to grep — keep it small, stable, and free of internal types
  • src/internal/ is where real engineering happens — templates, exceptions, RAII, whatever C++ idioms fit; none of it crosses the C-ABI boundary directly
  • tests/ never depends on anything JVM/Kotlin — it must build and run with a plain C++ toolchain alone, so CI can run it before the Kotlin side even compiles

Step 2: The public C-ABI header

// native/include/vulkanrenderer/vulkanrenderer.h
#ifndef VULKANRENDERER_H
#define VULKANRENDERER_H

#ifdef __cplusplus
extern "C" {
#endif

typedef struct VrRenderer VrRenderer;   // opaque handle — internals never exposed

VrRenderer* vr_renderer_create(int width, int height);
void        vr_renderer_destroy(VrRenderer* renderer);   // every _create has a _destroy
int         vr_renderer_draw_frame(VrRenderer* renderer);

#ifdef __cplusplus
}
#endif
#endif
  • extern "C" blocks even though the implementation is C++ — this is what makes the symbols callable from both JNI (GetProcAddress-style dynamic loading) and Kotlin/Native cinterop's .def file parsing without name-mangling issues
  • opaque pointer handles (VrRenderer*), never a struct with C++ members exposed by value
  • every _create paired with a _destroy — kotlin-multiplatform-jni-pro's own memory-safety discipline depends on this pairing existing at the native layer, not invented at the bridge
  • using C's uint8_t/uint16_t/uint32_t/uint64_t in the header is fine and often correct (pixel formats, bit flags, checksums) — but the two Kotlin sides handle it differently: Kotlin/Native cinterop maps them directly to UByte/UShort/UInt/ ULong automatically, while JNI has no unsigned primitive at all — see kotlin-multiplatform-jni-pro's type-mapping reference for the JNI-side conversion. Verified against kotlinlang.org's own unsigned-integer-types docs: don't use unsigned types for sizes/indices/array lengths in the header, even though C conventionally does for those — Kotlin's own guidance is to keep those signed

Step 3: CMakeLists.txt — one project, every platform

cmake_minimum_required(VERSION 3.22)
project(vulkanrenderer CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(vulkanrenderer SHARED
    src/vulkanrenderer.cpp
    src/internal/renderer_impl.cpp
)
target_include_directories(vulkanrenderer PUBLIC include)

# Android NDK links against the NDK's own Vulkan loader; Desktop/iOS link the system SDK —
# branch here, not in a second CMakeLists.txt.
if(ANDROID)
    target_link_libraries(vulkanrenderer PRIVATE vulkan android log)
else()
    find_package(Vulkan REQUIRED)
    target_link_libraries(vulkanrenderer PRIVATE Vulkan::Vulkan)
endif()

enable_testing()
add_subdirectory(tests)

Wiring per platform:

  • Android: externalNativeBuild { cmake { path = file("../native/CMakeLists.txt") } } in the library module's build.gradle.kts
  • iOS / Kotlin-Native: build vulkanrenderer as a static lib, then point a .def file at include/ — kotlin-multiplatform-jni-pro's cinterop guidance takes over from here
  • Desktop/JVM: build the shared lib, load it via System.loadLibrary("vulkanrenderer") in the JNI bridge kotlin-multiplatform-jni-pro writes

Step 4: Handoff to kotlin-multiplatform-jni-pro

Once native/include/<library>/<library>.h compiles and its public functions are stable, that header is the input to kotlin-multiplatform-jni-pro's Phase 0 (library-first discovery) — treat this native core exactly like any other 3rd-party library from that point on: read-only from the Kotlin side, discovered via its header, wrapped via the C-shim/wrapper patterns that skill documents. Do not start writing external fun declarations before the header has stabilized — churn in the header means churn in every JNI stub built against it.


Testing

// native/tests/vulkanrenderer_test.cpp
#include <gtest/gtest.h>
#include "vulkanrenderer/vulkanrenderer.h"

TEST(VulkanRenderer, CreateAndDestroyDoesNotCrash) {
    VrRenderer* renderer = vr_renderer_create(1920, 1080);
    ASSERT_NE(renderer, nullptr);
    vr_renderer_destroy(renderer);
}

TEST(VulkanRenderer, DrawFrameReturnsZeroOnSuccess) {
    VrRenderer* renderer = vr_renderer_create(1920, 1080);
    EXPECT_EQ(vr_renderer_draw_frame(renderer), 0);
    vr_renderer_destroy(renderer);
}
# native/tests/CMakeLists.txt
find_package(GTest REQUIRED)
add_executable(vulkanrenderer_test vulkanrenderer_test.cpp)
target_link_libraries(vulkanrenderer_test PRIVATE vulkanrenderer GTest::gtest_main)
add_test(NAME vulkanrenderer_test COMMAND vulkanrenderer_test)

Run via ctest in its own CI job — independent of ./gradlew jvmTest, so a native regression is caught before it ever reaches the Kotlin side.


Common Anti-Patterns

  • Writing JNI/cinterop glue before the native header has stabilized — every header change forces a matching bridge rewrite; finish Step 2/3 first, hand off per Step 4
  • Exposing C++ STL types (std::vector, std::string) or exceptions directly at the extern "C" boundary — neither JNI nor Kotlin/Native cinterop can cross them safely; convert to plain arrays/length pairs and error codes at the boundary, keep STL internal
  • A struct with C++ member functions or virtual methods passed by value across the boundary — use an opaque pointer handle instead; the boundary should never need to know the struct's real layout
  • Duplicating CMake logic per platform (a separate CMakeLists-android.txt, CMakeLists-ios.txt) instead of one project with platform branches — guarantees the two drift
  • No native-side test coverage, relying on the Kotlin test suite to catch native bugs — a native regression should fail ctest before a single line of Kotlin runs
  • Treating this skill's output as done and skipping kotlin-multiplatform-jni-pro — a stable header is necessary but not sufficient; the actual bridge still needs that skill's memory-safety and type-mapping discipline

Related Skills

  • kotlin-multiplatform-jni-pro — always the next step after this skill; bridges Kotlin to the native core this skill produces, and is the skill to use instead when the native code already exists as a 3rd-party dependency
  • kotlin-multiplatform-expect-actual — for native needs simple enough that a plain Kotlin/Native implementation covers it without a separate C/C++ core at all
  • kotlin-multiplatform-library-publishing — a library with a native core still ships through the normal Maven Central / XCFramework flow; the native build just becomes part of what each platform target compiles
  • kotlin-multiplatform-api-mimicry — if the native core also needs a mimicked higher-level Kotlin API shape on top (e.g. a Compose-inspired DSL over a Vulkan renderer), that skill covers the Kotlin-side ergonomics once this skill's core exists

Output Style

When asked to scaffold or structure a native core, respond in this order:

  1. recommendation (one native/ dir, one CMakeLists.txt, C-ABI header first)
  2. directory layout for the specific native core requested
  3. the public header — opaque handles, extern "C", paired create/destroy
  4. CMakeLists.txt with the actual per-platform link requirements named
  5. the explicit handoff point to kotlin-multiplatform-jni-pro

Keep the header snippet to the functions actually requested — do not invent a fuller API surface than what was asked for.


Changelog

Date Change
2026-07-31 Added a note on C unsigned integer types in the public header — cinterop maps them directly to Kotlin's UByte/UShort/UInt/ULong, JNI has no unsigned primitive at all (see jni-pro's type-mapping reference); also flagged that sizes/indices should stay signed even where C convention uses unsigned, per kotlinlang.org's own guidance.
2026-07-31 Initial release.