C & C++ Interoperability
Kairo provides zero-overhead, bidirectional interoperability with C and C++. There is no serialization layer, no binding generator, and no runtime bridge. Kairo emits ABI-compatible object code and consumes C/C++ headers directly.
The guarantee that makes this work is not a clever calling convention. It is that Kairo ships its own pinned Clang, and every translation unit on both sides of the boundary goes through it. The failure mode that breaks C++ interop for most languages (header parsed by compiler A, code compiled by compiler B, ABI mismatch discovered at runtime) is designed out rather than mitigated.
This page covers the toolchain model, calling C/C++ from Kairo, exposing Kairo to C/C++, inline assembly, pointer and reference passing, templates and concepts, allocators and ownership, the exception model, and the ABI contract enforced at link time.
In this section
- kairo, kcc & Cross-compilation
- Calling C and C++ from Kairo
- Using Kairo in C++
- Allocators & Ownership
- Exceptions & Panics
- ABI Contract & Verification
Coverage Matrix
What crosses the boundary, feature by feature. Each row is rated in two directions:
- C++ → Kairo: Kairo code uses the C or C++ feature, through an
ffiimport. - Kairo → C++: C or C++ code uses the Kairo feature, through
#include "x.k"or a generated header.
Each direction cell holds one of:
- ✅ works
- ◐ partial: the Notes say what does not work yet
- ❌ not supported, or not compiled yet
-
- n/a: the feature exists on one side only; nothing to rate in this direction
- ? not documented yet
Kairo-only and C++-only in the Notes mark a feature with no counterpart on the other side, and say what it becomes across the boundary. "Not yet" follows Implementation Status.
| Feature | Kairo uses it from C/C++ (C++ → Kairo) | C/C++ uses it from Kairo (Kairo → C++) | Notes |
|---|---|---|---|
| Toolchain and linkage | |||
| Using the other side's declarations | ✅ | ◐ | C and C++ headers import with ffi "c" / ffi "c++"; Objective-C headers cannot be imported yet. C++ and Objective-C++ files use Kairo through #include "x.k" (kcc) or --emit-headers; plain C and Objective-C files cannot include a .k yet (Status) |
C and C++ linkage (ffi "c", ffi "c++") | ✅ | ✅ | ffi "c" follows extern "C" rules: no classes, overloading or templates. See The ffi keyword |
| Name mangling and platform ABI | ✅ | ✅ | Itanium or MSVC, taken from Clang's own mangler; vtables, RTTI and struct layout follow the platform. See ABI Compatibility |
Layout-affecting C++ flags (-fno-rtti, -fshort-enums, packing) | ❌ | - | C++-only. Rejected in any translation unit that touches Kairo types. See Layout-affecting |
| Namespaces and modules | ✅ | ✅ | A module path is its C++ namespace, and module blocks are namespaces. C++'s std is cxx::std:: in Kairo; Kairo's library is kairo:: in C++. A module that only re-exports has no header. See Namespace Mapping and Modules |
| Argument-dependent lookup | ◐ | - | C++-only. Operators are always found by ADL. An unqualified call of a function found only by ADL is not found unless a Kairo function of that name is visible (Status); qualify it |
C++20 named modules (import std;) | ❌ | ❌ | Neither consumed nor produced. See A Note on C++ Modules |
| C and C++ preprocessor macros | ◐ | - | C++-only. Macros are expanded inside the imported headers before Kairo sees the declarations. defined! sees the target's predefined macros and every macro the file's ffi headers define |
A #define constant used as a Kairo value | ❌ | - | C++-only. An object-like macro (#define N 4) cannot be named in Kairo: N is R020E, an undeclared identifier, because no macro crosses the boundary. Wrap the value in the header as a constexpr (constexpr int K = 6; is a Kairo value, and eval X: i32 = sq(3) calls a constexpr function); defined! tests that a macro exists |
Kairo macros (macro m!) | - | - | Kairo-only. Token substitutions expanded before parsing; C++ gets only the code they expand to. See Macros |
Inline C++ (inline "c++", __inline_cpp) | ❌ | - | __inline_cpp no longer exists (R020E, an undeclared identifier). Import the declarations with ffi "c++" instead. See Namespace Mapping |
Inline assembly (inline "asm") | - | - | Kairo-only syntax, in an unsafe block, with GCC-style outputs, inputs and clobbers. A function that uses it is called like any other. See Inline ASM |
| Types | |||
Integers, floats, bool | ✅ | ✅ | Fixed C++ equivalents (i32 is std::int32_t, f64 is double; i64 is the target's int64_t). Fixed-width integers widen into size_t / ptrdiff_t parameters where that is lossless. See Primitives and Argument conversions |
Characters (char, C's char, wchar_t, char16_t, char8_t, byte) | ✅ | ✅ | C's char is std::c_char, a third type beside i8 and u8. wchar_t, char16_t and char8_t are std::c_wchar, std::c_char16 and std::c_char8, not integers. Kairo's char is char32_t, byte is std::byte |
| C bit-fields | ✅ | - | C++-only. Read and written from Kairo; a write wraps at the field's width. See Primitives |
| Structs | ✅ | ✅ | C layout and calling convention. In C++ a Kairo struct is a plain aggregate with public fields. A bodiless ffi "c" struct T names a header's tagged struct (Tags and ordinary names). See Structs |
| Unions | ✅ | ✅ | Untagged, laid out by the C++ ABI. See Unions |
| Plain enums | ✅ | ✅ | enum Dir derives u8 is enum class Dir : std::uint8_t. An imported C or C++ enum is always open. See Enums |
| ADT enums (variants with payloads) | - | ◐ | Kairo-only. To C++, a class holding the tag and the payload storage: it can be held, passed and returned, and built and inspected through Kairo functions. No C++ API over the variants is documented. It has no default value, so map::operator[] with one as the element fails (Status). See ADT Enums |
| Tuples | - | ✅ | Kairo-only. ::builtin::TupleN<T0, ...>, a plain struct template with fields _0, _1, ..., so every translation unit agrees on the type; C++ can name, return and specialize on it. C++'s std::tuple / std::pair are ordinary class templates. See Tuples across the boundary |
Nullables (T?) | - | ◐ | Kairo-only. ::builtin::Nullable<T>, with null as ::builtin::null; *T? is pointer-sized, and a closed enum's E? is the enum's size. Not yet: bool? is two bytes, not one (Status). A nullable can be a C++ template argument (vector<i32?>). See Nullables Across the Boundary |
Pointers (*T, unsafe *T) | ✅ | ✅ | A safe *T is T* in C++. Passing a pointer to a C or C++ function needs an unsafe block; unsafe &x makes a raw pointer from a safe binding, and an unsafe *T is C's T*. A C++ container keeps the pointer kind written (vector<*Node>). See Pointers and References |
C++ references (T&, const T&, T&&) | ✅ | ✅ | Reference parameters are the parameter modes @inout x: T, x: T and @move x: T, in both directions. A call returning a reference is usable as an operand and as an assignment target (Reference returns). const T&& can be called, not declared |
C++ smart pointers (unique_ptr, shared_ptr, weak_ptr) | ◐ | ? | Usable as imported class templates: a header function returning std::unique_ptr<int> or std::shared_ptr<int> is called and read with .get(), and cxx::std::make_unique<i32>(9) works. Their automatic mapping to std::Unique / Shared / Weak (Smart Pointer Promotion) is part of Tether, which is not in this release. How Kairo's own smart pointers look to C++ is not documented |
| Function pointers | ✅ | ✅ | int (*)(int) imports as unsafe fn(i32) -> i32 and takes a named function or a closure that captures nothing. A Kairo unsafe fn is a plain C function pointer, and so is every fn parameter of an ffi "c" function. See Function pointers and callbacks |
Closures and fn values | ◐ | ◐ | A fn(i32) -> i32 value is ::__kairo_fn<std::int32_t(std::int32_t)> in C++. Kairo to C++: a closure, capturing or not, can be passed to a C++ template parameter (template<class F> int call(F f, int x)), but not to a std::function parameter (SC063E, no matching overload). C++ to Kairo: a function, or a captureless lambda converted with unary + (+[](int x) { return x + 1; }), is passed where Kairo takes a fn; a lambda written without the +, a capturing lambda and a std::function are compile errors. A capturing closure, or any fn value, passed where a C function pointer is expected is a compile error. Not yet: generic closures. As a C++ template argument a written fn(A) -> R is the C++ function type R(A) (function_ref<bool(int)>), while a raw unsafe fn(A) -> R is the pointer R(*)(A). See Closures |
Arrays ([T; N], C arrays) | ✅ | ✅ | A Kairo array is passed to a C++ const int (&)[3] parameter, and a C++ global array is reached through a pointer to its first element (unsafe &g[0]). A const [T; N] parameter is const T (&)[N] in C++, and a C++ array binds to it. An array is not copyable: var a = g_arr is SC083E. cxx::std::array<i32, 4> works as an imported template. See Collections |
| Slices, vectors, maps, sets | - | ◐ | Kairo-only. Plain class templates in the ::builtin library, used from C++ through the same include: a vector [T] is ::builtin::containers::vector::Vector<T> (size(), operator[], push_back), a slice is Slice<T> (data and len fields, built from a pointer and a length), and a map {K: V} is HashMap<K, V> (size(), contains, operator[], begin() / end() over entries with key and value, so C++'s range for works); a set is HashSet<T>. Vector, set and map literals compiled and ran in a test of 0.2.0; the Status page lists what is left. C++ containers are used through cxx::std::. See Collections |
| Strings | ◐ | ◐ | A const char* is *const c_char. A string literal is a C string at a const char* parameter (and through C's ...); any other Kairo string passes s.c_str() (Strings and const char*). std::string is an imported class. To C++, a Kairo string is ::builtin::string::string: size(), c_str(), a copy constructor, and a constructor from const unsigned char* (not const char*, so a C++ string literal needs a cast). Through #include "x.k" the class is complete only where the .k has a type that holds a string by value; a function that merely returns one leaves it incomplete in C++ ("incomplete return type"), which --emit-headers plus #include "builtin/string.hh" avoids |
| f-strings | - | - | Kairo-only. A *const c_char prints as a pointer: there is no C-string formatter yet. See Status |
| Type aliases | ✅ | ✅ | C and C++ typedefs and using aliases import (typedef struct X X is one type). A Kairo member type alias is a C++ member using at the same access; top-level aliases are not documented. See Type Aliases |
| Functions | |||
| Functions and methods | ✅ | ✅ | A Kairo method in the class body is a C++ member function. See What a Kairo declaration looks like in C++ |
| Overloading | ✅ | ✅ | An imported overload set is ranked as C++ ranks it, parameter modes included; a header that overloads f(T) against f(const T&) is an error at the import. See Overloading |
| Default arguments | ✅ | ✅ | C++ applies an imported function's defaults, so only trailing arguments can be left out (SC107E). A Kairo default reaches C++ callers: pub fn dflt(a: i32, b: i32 = 10) is called as lib::dflt(1) and returns 11 |
| Named arguments | - | - | Kairo-only. Work on imported functions, but cannot skip an earlier defaulted parameter. See Named arguments |
C variadic functions (...) | ✅ | ? | Callable from Kairo (printf). Whether Kairo can declare a C-variadic function, and how C sees it, is not documented: the declaration forms tried (fn f(n: i32, ...), fn f(*const c_char, ...)) were syntax errors |
| Variadic templates and packs | ✅ | ◐ | A C++ forwarding pack (Args&&...) takes any number of arguments (Template arguments). A Kairo ...xs: T is one Slice<T> parameter in C++, so C++ passes a slice, not a list of arguments (lib::sum(1, 2, 3) is an error). The C++ form of generic variadic functions is not documented |
where dispatch | - | ✅ | Kairo-only. Each group is one C++ function under its public name; the candidates stay private. See where |
Function hints (@hot_path, @cold_path, @pure, @no_inline, fn f() const) | - | ✅ | Kairo-only. Emitted as [[gnu::hot]], [[gnu::cold]], [[gnu::pure]], __attribute__((noinline)), [[gnu::const]]. See Function hints |
Calling conventions (@preserve_most, @preserve_all, @preserve_none) | - | ❌ | Kairo-only. Never on a function C or C++ can see (SC136E): only priv and local functions. See Calling conventions |
eval (compile-time) | ✅ | ✅ | An imported eval constant is a compile-time constant to C++ code that includes the module, and an eval value is a valid C++ template argument (array<i32, N * 2>). A C++ constexpr function is called in Kairo's eval (eval X: i32 = sq(3) is 9), and a constexpr variable is a Kairo value. See Eval |
Global and static variables | ✅ | ✅ | C and C++ globals import (glibc's timezone). A namespace-scope static const is a C++ const variable, a class member a static const data member. See Static Variables |
| Generics | |||
| Templates and generics | ◐ | ✅ | Imported templates take Kairo types and values as arguments, and are chosen as C++ chooses them, SFINAE included. Not yet: a ranged for over an imported template inside a generic Kairo function over its own T (an internal error), a defaulted non-type parameter that depends on an earlier one (Status). Kairo generics are C++ templates, bodies included. See Templates and Concepts and Generics |
C++ concepts and Kairo impl bounds | ◐ | ◐ | A C++ concept imports as a constraint-only interface, usable as a Kairo bound; a concept-constrained template imports as a generic. An overload set told apart by a concept that calls a method of a Kairo class you pass is chosen correctly. A Kairo interface is a C++ concept, and an impl bound on a generic function or method is a requires clause; a bound on a generic class or struct is not translated, so a bad C++ instance fails inside the member that needs it. See Templates and Concepts and Generics |
requires clauses | ✅ | ◐ | A C++ requires clause, enable_if, decltype return or void_t test that fails removes the candidate, as in C++. A Kairo requires clause on a generic function or method is a static_assert in the C++ template body, not a C++ requires: a failing call is a hard error, not a removed candidate |
| Virtual interfaces | - | ❌ | Kairo-only. Not compiled yet: a call through a pointer to an interface is an internal compiler error. Dispatch through a base class with virtual methods instead. See Virtual Interfaces |
| Classes | |||
| Classes | ◐ | ✅ | Imported C++ classes are constructed and called directly. Not yet: inherited constructors (using Base::Base;) are not callable (SC063E). Kairo classes keep their layout and vtables; copy and move constructors and the destructor (op finally) are public in C++ so C++ containers can hold the type. See Classes |
Inheritance (derives) | ✅ | ✅ | A Kairo class can derive a C++ class, and a C++ class a Kairo one, abstract classes included. Every base is a public C++ base; a priv or prot base narrows its members through using-declarations. See Inheritance |
| Multiple inheritance | ✅ | ✅ | A Kairo class with several bases has the platform's C++ layout, and a Kairo class can derive from several C++ classes (class M derives A, B1; the fields of both are readable). See Multiple inheritance |
| Virtual methods and abstract classes | ✅ | ✅ | Vtable-compatible both ways. A C++ override of a Kairo virtual fn must be noexcept unless the Kairo method is @unwind; a Kairo override of a noexcept C++ virtual must not be @unwind. See Virtual Dispatch |
Access control (pub, prot, priv) | ◐ | ✅ | priv is private:, prot is protected:; the class befriends its file's functions. Struct fields are public in C++. A priv top-level declaration does not cross unless a pub inline or generic body names it. Kairo does not check C++ access itself: reading a private member of an imported class is refused by the generated C++ and reported as an internal error (I003E), not a Kairo access diagnostic. See What crosses an include |
extend | - | ✅ | Kairo-only. An extension member is not a C++ member function: it is a static function of a companion struct beside the type, taking the receiver as its first parameter, and a same-file extend's companion is a friend of the type, so priv access works. An extension operator is also a free C++ operator. See Using Kairo in C++ |
RTTI and dynamic_cast | ✅ | ✅ | Kairo's checked downcast p as *D? compiles to dynamic_cast, and Kairo classes carry the platform's RTTI. It works on an imported polymorphic C++ class too: a as *D? is non-null for a D and null for a plain A. See Casting |
| Operators | |||
| Operator overloading | ✅ | ✅ | C++ member operators, free operators found by ADL, hidden friends and operator templates all apply; unary * calls operator*. A Kairo op is a C++ operator. See Operators on C++ types |
Three-way comparison (<=>) | ✅ | ✅ | On a C++ operand, < and the other relational operators fall back to <=> as in C++20, and != to !(a == b). Kairo's op <=> returns Ordering. See Derived comparisons |
for over a range | ✅ | ✅ | An imported C++ class iterates through begin() / end(), members or found by ADL (for). C++'s range for works over a Kairo map (begin() / end() over entries). A Kairo type's own op in in C++'s range for is not documented |
| Errors | |||
Panics (panic, try / catch) | - | ✅ | Kairo-only. C++ gets the [[nodiscard]] result union and reads it with ::builtin::ok, value, is<E>, error<E>, site, or converts it to an exception with value_or_throw. The error's source location is found on ELF targets only so far. A C++ type can be panicked as a value. See The value API |
| C++ exceptions | ◐ | ❌ | C++-only. Caught by catch e: cxx::std::exception in either try form, provided every Kairo frame in between is @unwind; a noexcept Kairo frame terminates the program. Not yet: printing what() in an f-string. Kairo never throws by design: C++ code may convert a result with value_or_throw. See Exceptions |
@unwind, @no_unwind, -funwind | - | ✅ | Kairo-only. Every Kairo function is noexcept in C++; @unwind (or -funwind) removes it so a C++ exception can pass through. Not yet on a closure. See C++ exceptions through Kairo frames |
| Memory | |||
Heap allocation (@create, @destroy) | - | ✅ | Kairo-only. @create T(args) and @destroy p compile, with no import needed; the initializer form @create T{...} is not compiled yet (SC116E, Status). Its pointer is a plain T* to C++: free it through Kairo (@destroy), or from C++ with a delete of a Kairo type (see the next row), never with free() (What is still an error). See Heap Allocation |
C++ new / delete on Kairo classes | - | ✅ | Every Kairo class, struct and ADT enum in C++-facing output (an --emit-headers header, #include "x.k") carries class-scope operator new / operator delete functions bound to Kairo's global allocator, so C++'s new / delete of a Kairo type goes through Kairo's allocator. Kairo code cannot define or overload them; a class defines only its constructors and destructor. See Class-specific operator new and operator delete |
@cxx::new / @cxx::delete | - | ✅ | Kairo-only. @cxx::new T(args) is a plain C++ new T(args) (an unsafe *T), @cxx::new [T; n] is new T[n], @cxx::delete p is delete p and @cxx::delete [] p is delete[] p: for memory that crosses into or comes from C++. See Memory that belongs to C++ |
Global allocator (@set_global_allocator) | ✅ | ✅ | The global allocator is five C symbols: C or C++ can supply them, and C can call them. See The global allocator ABI |
CxxNewAllocator | ❌ | - | Specified, but not in the 0.2.0 library: @set_global_allocator(CxxNewAllocator) is R021E, an unknown type name. See CxxNewAllocator |
| Scoped allocators | - | ? | Kairo-only. Specified to never reach a C++ delete, which relies on the class-specific operators above and on Tether, which is not in this release. See Scoped allocator |
| Ownership and lifetime attributes in headers | - | ❌ | Kairo-only. Clang's ownership_returns / ownership_takes, lifetimebound and gsl::Owner / gsl::Pointer are derived from Tether and come with Stage 2 (ABI stability). See Ownership annotations |
| Tether (lifetime analysis) | - | ❌ | Kairo-only. Not in this release. As designed, a raw pointer from C++ is untracked, a pointer handed to C++ loses its facts, and a function C++ can reach is treated as entered from an unknown thread. See Tether: C/C++ Interop |
| Concurrency | |||
thread variables | ✅ | ✅ | A Kairo thread variable is a C++ thread_local (lib::tv reads 5 from C++). A C++ thread_local is read and assigned from Kairo. See Thread-Local Variables |
| Generators and coroutines | ? | ◐ | Kairo generators (-> yield T) compile to C++20 coroutines. C++ gets ::builtin::coro::generator::Yield<T> and drives it with next() and current() (a loop summing two yielded values gave 3). A C++ coroutine type consumed from Kairo is not documented. Yielding a literal fails in the C++ step. See Generators |
async, await, spawn, thread f() | ❌ | ❌ | Not compiled yet: see Concurrency and Status. A test with async fn was a syntax error (S052E) |
A Note on C++ Modules
C++20 named modules (import std;, import my_module;) are not currently supported. The interop layer relies on header-based inclusion via Clang's preprocessor, and module interface deserialization (consuming pre-compiled BMIs) is a future roadmap item.
Exporting Kairo code as a C++ module interface unit (.cppm) is also planned but not yet implemented.
For now: use header-based interop (ffi "c++" + kcc) for all cross-language boundaries.