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/actualKotlin/Native implementation viakotlin-multiplatform-expect-actualmay 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:
- One
native/directory, oneCMakeLists.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. - 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 whatkotlin-multiplatform-jni-pro's Phase 0 discovery will read once bridging starts. - 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/. - Native tests run independently, via ctest, in their own CI job — not bundled into
the Kotlin
jvmTesttask, 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 directorykotlin-multiplatform-jni-pro's Phase 0 discovery should ever need to grep — keep it small, stable, and free of internal typessrc/internal/is where real engineering happens — templates, exceptions, RAII, whatever C++ idioms fit; none of it crosses the C-ABI boundary directlytests/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.deffile parsing without name-mangling issues- opaque pointer handles (
VrRenderer*), never a struct with C++ members exposed by value - every
_createpaired 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_tin 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 toUByte/UShort/UInt/ULongautomatically, while JNI has no unsigned primitive at all — seekotlin-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'sbuild.gradle.kts - iOS / Kotlin-Native: build
vulkanrendereras a static lib, then point a.deffile atinclude/—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 bridgekotlin-multiplatform-jni-prowrites
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 theextern "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
ctestbefore 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 dependencykotlin-multiplatform-expect-actual— for native needs simple enough that a plain Kotlin/Native implementation covers it without a separate C/C++ core at allkotlin-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 compileskotlin-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:
- recommendation (one
native/dir, one CMakeLists.txt, C-ABI header first) - directory layout for the specific native core requested
- the public header — opaque handles,
extern "C", paired create/destroy - CMakeLists.txt with the actual per-platform link requirements named
- 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. |