Experimental Native C API

CNA snapshot c1c316b9  ·  product 0.1.0-alpha.1  ·  declared C ABI 0.46.0  ·  built and tested in local runs on Linux and macOS, not by any CNA CI workflow

Snapshot status and scope

CNA_BUILD_C_API is an opt-in CMake option (default OFF) for a native C linkage layer under CNA/C/. At source level, that layer uses fixed-width values, versioned structures, opaque generation-checked handles, explicit result codes, count/copy string and buffer protocols, and callbacks instead of exposing C++ classes or STL types. The exported surface does not vary with configuration: a route whose backend is compiled out still exists and answers CNA_RESULT_NOT_SUPPORTED.

The first rows are facts about the source surface and its recorded metadata. The last row is evidence recorded in campaign ledgers (CNA.NET’s, 4 October 2026, and CNA’s plans/plan_apple_m4.md, tasks AM4-209 to AM4-214), not by CNA’s CI and not by the authors of these pages. Treat the C library as a pre-release that you build and test yourself.

From the alpha.1 compile blocker to a built library

At the alpha.1 tag the library could not compile: RendererIdentities in modules/c-api/src/CnaCApiCoreExt.cpp held one row fewer than the canonical C++ renderer count, and the file deliberately checks the two against each other (an isolated GCC 14.2/Ninja build reproduced comparison reduces to (49 == 50); with networking off, configuration failed on a missing GamerServices include instead).

At this snapshot the table has 14 rows against 14 canonical identities, and the ceiling constant equals the highest published value. Both compile-time checks hold:

static_assert(RendererIdentities.size() == CanonicalRendererCount(),
              "A renderer was added to CNA::GraphicsRendererType without a C identity.");
static_assert(CNA_GRAPHICS_RENDERER_MAXIMUM == HighestPublishedIdentity(),
              "CNA_GRAPHICS_RENDERER_MAXIMUM must name the highest-valued published renderer "
              "identity.");

The networking trap is a deliberate configure-time error naming the option: CNA_BUILD_C_API=ON requires CNA_ENABLE_NET=ON, because the C API exports the GamerServices routes and links the GamerServices module unconditionally.

Build, package and consume

Enabling CNA_BUILD_C_API=ON turns on C as a project language, uses C17 for CNA’s implementation targets (with C extensions off inside modules/c-api, and -Wall -Wextra -Wpedantic -Werror there), and forces position-independent code. The public headers are held to a C99 consumer floor, checked against a matrix of language modes and toolchains (C99/C11/C17 and C++11/14/17 are required cells; 23 declared cells across 7 toolchains).

The C++ framework itself still has no install() rules; only this C package is installable. To build and install just the C ABI from a source checkout of the apple/m4-stabilization branch (with the sibling checkouts described in Building):

cmake -S . -B build -DCNA_BUILD_C_API=ON          # CNA_ENABLE_NET defaults to ON
cmake --build build --target cna_c_api
cmake --install build --component CNACApi --prefix /opt/cna

and, in a consumer project that has never heard of the CNA source tree, the shape CNA’s own example uses:

cmake_minimum_required(VERSION 3.20)
project(my_cna_game LANGUAGES C)

find_package(CNA 0.1 CONFIG REQUIRED)
add_executable(my_cna_game main.c)
set_target_properties(my_cna_game PROPERTIES C_STANDARD 99 C_STANDARD_REQUIRED ON C_EXTENSIONS OFF)
target_link_libraries(my_cna_game PRIVATE CNA::CApi)

Without CMake, the library is a plain shared object with C linkage: cc -std=c99 -I/opt/cna/include main.c -L/opt/cna/lib -lcna_c_api. See the CNA repository’s CONSUMING.md for the full consumption notes; where it says every minor within a major is additive, or that the device is legal only inside a callback, the version history and the threading section below are newer.

WebAssembly artifact

Under Emscripten the target cna_c_api_wasm emits an ES6 module (cna_c_api.mjs plus .wasm, createCnaCApi factory, ALLOW_MEMORY_GROWTH=1, ASYNCIFY=0) whose export list is generated from the headers by tools/c-api/generate_wasm_exports.py, and the static C archive can also be linked into another runtime’s WebAssembly module, as CNA.NET’s browser host does. Its ABI notes (by-value uint64_t arrives as BigInt, copied strings carry no NUL) are in CNA’s WASM_ARTIFACT.md. A browser host drives the game one frame at a time with cna_game_run_frame_ext from requestAnimationFrame; a threaded build (CNA_ENABLE_EMSCRIPTEN_THREADS=ON) can run the game thread as a browser worker. Three CTest registrations cover the module (CApi_WasmLinkContract, CApi_WasmModuleSmoke, CApi_WasmBrowserProbe); none runs in CI.

The C ABI version is not the product version

#include <CNA/C/cna.h>

if (cna_get_abi_version() != CNA_ABI_VERSION) {
    return 1;
}

CNA_ABI_VERSION_MAJOR, _MINOR and _PATCH are fixed-width macros, encoded by CNA_ABI_VERSION_ENCODE as major<<16 | minor<<8 | patch. Do not compare them with CNA_VERSION_*; the latter describe the C++ product build. The exact-equality check above is the strictest and, while the ABI is 0.x, the safest one — it is also what CNA.NET does; CNA’s example accepts any equal-or-newer minor of the same major, which is a looser bet (see the next section).

ABI version policy and history

While the ABI is 0.x, an incompatible change requires a minor-version increment, release notes and a regenerated baseline; from 1.x on only additive changes are permitted within a major. ABI 1.0 is a separate decision the release gate explicitly does not make. CMake’s find_package(CNA 0.1 CONFIG) accepts any same-major version at or above the one requested, so CMake accepting the package is not a compatibility promise across 0.x minors: since alpha.1, 0.28.0 and 0.29.0 and the steps from 0.30.0 to 0.35.0 were incompatible, 0.40.0 and 0.42.0 to 0.44.0 changed rules without changing exports, and the current 0.46.0 declares a different constant set from 0.44.0, so a binding written against older headers must be regenerated or re-reviewed. A program that must not break should compare the minor it was written against at run time, not only the major.

The full table lives in CNA’s ABI_VERSIONING.md. The recorded baseline is enforced by a generator (generate_abi_baseline.py, registered as the CTest gates CApiAbiHeaderBaseline and, where a library exists, CApiAbiBaseline).

Renderer identity values

CNA_GraphicsRendererType is a stable, sparse integer identity: a renderer’s value never changes and a reserved value is never reused, so the numbers from CNA_GRAPHICS_RENDERER_UNKNOWN (0) to CNA_GRAPHICS_RENDERER_MAXIMUM (currently 43, FNA3D) contain gaps. The 14 identities keep fixed values (for example CNA_GRAPHICS_RENDERER_VULKAN is 8), and every route that takes an identity refuses a reserved value or anything above MAXIMUM with CNA_RESULT_INVALID_ARGUMENT. Because some reserved values lie above the current maximum, the next new identity will take 52, not MAXIMUM + 1. scripts/check_renderer_identities.py fails the build if a reserved value is reused.

An identity is not a support claim. Two builds carrying the same identity can answer capability queries differently, so branch on cna_graphics_device_supports_capability and the renderer-feature queries, never on the renderer name or number. The list of identities and what each one supports is on the Renderers page.

Programming model

The shipped example modules/c-api/examples/c/hello_cna.c (354 lines) is the reference: it checks the ABI, creates a callback-driven game, borrows the graphics device only during a legal callback, queries capabilities, exercises count-then-copy, provokes and reads two deliberate errors, creates and draws a texture, and shuts down in lifetime order. It is guarded so that it exits cleanly with no display.

Threads, frames and host-driven runs

By default every lifecycle, game, graphics, content, input, media, device and resource-destruction call belongs to the runtime’s creation thread, and a call from another thread answers CNA_RESULT_THREAD. The ABI generations since 0.36 add controlled exceptions to that rule, each opt-in or narrowly scoped:

CNA.NET is the main consumer of these routes: its browser host uses the host-driven run, and XNA games that start threads use the foreign-thread queue. CNA’s own CALLBACKS_AND_THREADING.md predates them; the header comments in runtime.h are authoritative.

Route families and the largest headers

The 60 headers under modules/c-api/include/CNA/C/ carry extern "C" guards, except the umbrella CNA/C/cna.h (which only includes the others) and the constants-only named_colors.h. The largest, by declared routes (lines starting CNA_C_API):

The opt-in CNAEXT extensions (retro effects and debug drawing) have 44 routes in graphics_ext.h. Not in the C ABI at all: Diagnostics and the Inspector have no C routes, and the build-time Content Pipeline, the Windows-Phone shell module, the platform substrate and the renderer implementations are out of runtime C scope by owner decision (see Measured coverage).

Your first C program

Tutorial 129 walks through a complete first program against ABI 0.46.0: install the CNACApi component, find_package(CNA 0.1 CONFIG REQUIRED), link CNA::CApi at C99, check the ABI, create a game with callbacks, borrow the graphics device, read the renderer name with count-then-copy, print the error diagnostic, and tear down children before the game. The tutorial is honest about the same caveat as this page: no CNA CI job builds the library, and the docs’ authors did not build it.

Measured coverage

CNA’s generated inventory (COVERAGE.md, produced by tools/c-api/generate_coverage_inventory.py) derives the complete public C++ declaration list from modules/*/include and maps every symbol through coverage_mappings.json. At this snapshot it reports 469 headers in scope, 8,142 symbols: 7,053 implemented in C, 15 approved partial mappings, 631 planned (not yet mapped) and 443 not applicable to a C consumer; 451 headers are explicitly excluded. The planned rows sit mostly in graphics (255) and content (204). These numbers describe the checked-in generated inventory; they do not convert partial or not-applicable rows into full C++ parity.

The 631 planned rows are the live backlog and the reason the committed release-gate report reads Not ready. CNA’s own coverage audit says an earlier “about 3,000 planned” figure was mostly mis-modelled evidence and that the genuinely missing runtime bindings measured 259 logical APIs before the scanner was repaired.

Gates and CI: what is actually checked

The C ABI has a large gate suite, but almost all of it is header-, JSON- or documentation-level. Nothing in it compiles the library.

The CNA.NET campaign’s final regression run on Linux x86_64 (CSX-153, 4 October 2026) records the native C API test set passing on a library built from an earlier CNA commit (ABI 0.44.0). CNA’s Apple campaign records every C API test passing on macOS for this branch: 119 of 119 in the SOFTWARE and SDL_RENDERER configurations on a physical Mac mini M4, with the exported symbols equal to the 3,210 declared routes and the installed package consumed shared and static. We did not reproduce either run; the definitive check for your toolchain is one out-of-source build of -DCNA_BUILD_C_API=ON followed by ctest -R '^CApi'.

Language bindings: maintained and archived

CNA is implemented in C++23, and this experimental C ABI is the one foundation every other language builds on. C++ is CNA’s native implementation language, not a binding. CNA actively maintains two language bindings: C, which is this ABI itself, and C#, through CNA.NET. Eight further bindings — Common Lisp, Go, Java, Python, Ruby, Rust, Swift and TypeScript — were developed during CNA’s history and are now archived.

CNA publishes one experimental C ABI and generates no language bindings. CNA’s own plan lists “a language-specific binding, wrapper, package, generator or sample for any language other than C” as a non-goal inside the CNA repository; every other binding is a separate project that consumes this ABI.

Maintained bindings: C and C#

Archived bindings: Common Lisp, Go, Java, Python, Ruby, Rust, Swift and TypeScript

Seven of them (Go, Java, Python, Ruby, Rust, Swift and TypeScript) were requalified on Linux against C ABI 0.35.0 on 30 September 2026, immediately before they were archived; Common Lisp stopped earlier, on 8 September 2026. Each row describes the binding at its final revision.

These rows are evidence for each repository’s own final revision, not for CNA at this snapshot: none of the eight admits ABI 0.46.0 as qualified. If you write your own consumer, the stable markers CNA publishes are: cna_get_abi_version() (encoded 0x00002E00 for 0.46.0), the CNA_ABI_VERSION macro, the CMake package version, the ELF symbol-version node CNA_C_API_0.1 (Linux) and the dylib’s Mach-O compatibility version (macOS), the machine-readable tools/c-api/abi_baseline.json (every struct layout, constant and export), the export/declaration set-difference gate check_declared_exports.py, and the per-artifact manifest from generate_artifact_manifest.py.

Important limitations

• No CNA CI job builds the C library. Run evidence comes from local campaign records — CNA.NET’s (Linux x86_64, plus Android-emulator and headless-Chromium hosts) and CNA’s Apple campaign (a physical Mac mini M4) — not from CNA’s CI and not from us.
• The release gate reads Not ready: 631 in-scope public C++ declarations still lack C mappings, and 443 more are recorded as having no C form (see CNA’s LIMITATIONS.md).
• The declared ABI 0.46.0 is experimental and pre-1.0. Several minor steps since alpha.1 were incompatible and more may follow; ABI 1.0 is a separate future decision.
• Package machinery, run path, export control and the consumer test exist for Linux/ELF and macOS/Mach-O (macOS measured locally on Apple silicon only); Windows shared-library consumption is not verified, and the C ABI is not exercised on iOS (the C API cannot be configured there today).
• Platform substrate interfaces that a C++ implementation would subclass are intentionally not exposed for C callers to implement.
• Some C++ overloads, containers and polymorphic values map to narrower typed routes or snapshots; 15 rows are explicitly partial.
• Thread, callback-borrow and shutdown rules are part of the contract. A numerically valid handle does not permit use on the wrong thread or after its owner shuts down; the cross-thread routes are opt-in and keep their own limits.
• CNA.NET is a separate beta project that pairs with exactly one ABI version, and the eight archived bindings are not updated at all; see Language bindings.

Continue with Tutorial 129: Your first C program against ABI 0.46.0, C# with CNA.NET, versioning, or the verification guide.