Releases & Versioning
Pre-1.0 software. CNA follows Semantic Versioning, but while the major version is 0 a minor release may change the public API, and neither the C++ API nor the experimental C ABI is promised stable before 1.0. Pin the tag or commit you build against, and rebuild C++ code whenever you move it.
Two revisions, one version string. CNA’s latest release is 0.1.0 (tag v0.1.0). Most pages on this site document a later revision — the development snapshot 3b43bd86 on the next branch, 948 commits after that tag — and that snapshot still reports itself as 0.1.0. It is not a new release, has no tag and is described only by the [Unreleased] section of CNA’s changelog; see the snapshot section.
The 0.1.0 release
| Product version | 0.1.0 |
|---|---|
| Git tag | v0.1.0 (annotated, “CNA 0.1.0”) |
| Resolved commit | 10a4ef1cb4cd832f761536d77588000104947f8d “chore(release): prepare v0.1.0”, cut from next |
| Tag date | 2026-10-10 16:34 +0200 |
| Required siblings | sharp-runtime 0.1.0, easy-gl 0.1.1, meta-gl 0.4.1 (or a later patch release of each), checked at configure time |
| Release status | The final 0.1.0 release, after the 0.1.0-alpha.1 pre-release; still pre-1.0 |
Browse the tagged source or its release changelog. For the first time the sibling checkouts CNA builds against are required rather than only recorded: cmake/DependencyVersions.cmake reads the version each sibling declares right after add_subdirectory and stops the configure step with the git checkout that fixes a mismatch (another minor line, a pre-release of the required version, or a checkout too old to declare a version); -DCNA_CHECK_DEPENDENCY_VERSIONS=OFF turns the error into a warning. The check compares versions, not commits.
CNA’s changelog records how the release was verified (CNA’s record, not repeated for this site): a cmake-build-multi tree on Debian 13 with GCC 14.2.0 configured with CNA: version 0.1.0 and the three accepted sibling versions, built with no errors, and ran 11,509 tests — 11,310 passed, 192 skipped by the tests’ own renderer conditions, and 7 failed: three failures that predated the release, three Wine-hosted XNA tests that need an X11 display the private runner does not give Wine, and one timing-sensitive test that passed three of three re-runs alone. Its known limitations also list renderer coverage as uneven by design and Content as having no general .xnb reader. At the release CNA had 14 renderer identities over 12 families and C ABI 0.46.0; both changed afterwards (below).
The first tagged release, 0.1.0-alpha.1
| Product version | 0.1.0-alpha.1 |
|---|---|
| Git tag | v0.1.0-alpha.1 |
| Resolved commit | 1bb2145d99ed572dd4eb15009c34e2e5f410fcf0 |
| Tag date | 2026-08-20 19:06:23 +0200 |
| Release status | First tagged pre-release, superseded by 0.1.0 |
The leading v belongs to the Git tag. The product version reported by CMake and C++ is the string without it. Browse the immutable alpha.1 source or its changelog. The repository publishes Git tags (v0.1.0-alpha.1, v0.1.0 and an audit marker, audit-2026-07-complete); this site does not rely on GitHub Release objects.
The development snapshot after 0.1.0
Development did not stop at the tag. The site’s reference revision is a commit on CNA’s integration branch next, chosen so that every claim can be checked against one immutable tree:
| Commit | 3b43bd8687ed46523d873f9bec4b32bd8481dcb5 (short: 3b43bd86) |
|---|---|
| Branch | next |
| Commit date | 2026-10-27 17:18 +0100 |
| Product version string | 0.1.0 — unchanged since the release; CNA_VERSION_STRING was not bumped and there is no newer tag |
| Distance from the tags | 948 commits after v0.1.0 (792 on the first-parent line, 4 merges); git describe reads v0.1.0-948-g3b43bd868. 4,657 commits after v0.1.0-alpha.1. The previous snapshot this site documented, c6dec91f (24 October 2026), is 136 commits earlier |
| Size of the change | 6,383 changed paths since v0.1.0; about +0.24 million and −0.97 million lines (the removals are mostly retired code, archived documents, the avatar catalog that moved into its own repository and the third-party patch files that became commits on CNA’s forks) |
| Release status | Unreleased development snapshot. It is not a release, carries no compatibility promise, and its changes are listed only under [Unreleased] in CNA’s CHANGELOG.md |
Because the version string did not change, CNA::getVersionString() cannot tell the release and the snapshot apart. If you need to know which one you built, record the Git commit (git rev-parse HEAD), not the product version. Where these docs say “this snapshot” they mean 3b43bd86; where they say “0.1.0” or “the release” they mean the v0.1.0 tag, and “alpha.1” means the first tag.
GitHub’s default branch is the 0.1.0 release. The repository’s default branch, main, points at the v0.1.0 commit. A plain git clone https://github.com/libcna/cna.git therefore gives you 0.1.0, and links of the form .../blob/main/... show 0.1.0 content. Link to the snapshot with a commit permalink such as .../tree/3b43bd8687ed46523d873f9bec4b32bd8481dcb5; .../tree/next keeps moving.
What "6,383 changed paths" counts
The 6,383 figure comes from git diff --shortstat v0.1.0 3b43bd86 with Git's default rename detection. That count treats each detected rename as one path. For a range this large, Git skips exhaustive rename detection and prints a diff.renameLimit warning. At these two commits Git's default name-status listing contains 587 additions, 4,083 deletions, 1,700 modifications and 13 renames. git diff --no-renames --name-status counts every rename as a deletion plus an addition and lists 6,396 records (600 / 4,096 / 1,700). Both figures are correct. The first counts files as Git pairs them; the second counts paths that appeared or disappeared. A comparison with another range should use the same flag and state it: from v0.1.0-alpha.1 to the snapshot the same commands give 10,273 (3,058 / 4,823 / 2,359 / 33 renames) and 10,306 records. (The previous snapshot, c6dec91f, gave 6,302 and 10,670 by the same commands.)
How to obtain each revision
| You want | Commands | Notes |
|---|---|---|
| The development snapshot these docs describe | git clone -b next https://github.com/libcna/cna.gitgit -C cna checkout 3b43bd8687ed46523d873f9bec4b32bd8481dcb5git -C cna submodule update --init | The second line pins the exact documented commit; the branch keeps moving. The third also checks out the avatar catalog, a submodule since 25 October 2026 (a configure with Gamer Services on stops without it; a GitHub ZIP or git archive export has no submodules). sharp-runtime must be its next branch (git clone -b next https://github.com/libcna/sharp-runtime.git): the snapshot uses sharp-runtime changes made after sharp-runtime’s own v0.1.0 tag, which still declare version 0.1.0 and so pass the configure check. easy-gl and meta-gl at v0.1.1 and v0.4.1. |
| 0.1.0, the latest release | git clone -b v0.1.0 https://github.com/libcna/cna.gitsiblings: git clone -b v0.1.0 .../sharp-runtime.git, -b v0.1.1 .../easy-gl.git, -b v0.4.1 .../meta-gl.git | Also what an unqualified clone of the default branch gives you. The release still had 14 renderer identities and C ABI 0.46.0. |
| alpha.1, the first tagged pre-release | git clone -b v0.1.0-alpha.1 https://github.com/libcna/cna.git | History only; the alpha.1 numbers on this site refer to this revision. |
Layout, system packages and the sibling checkouts are the same as in Getting Started and Building; the rows above differ only in which CNA and sibling revisions you check out.
Which sharp-runtime revision goes with each tag
Since 0.1.0 the build checks the sibling's declared version: the root CMakeLists.txt adds whatever checkout CNA_SHARP_RUNTIME_ROOT points at (default ../sharp-runtime), and cmake/DependencyVersions.cmake accepts sharp-runtime 0.1.0 or a later 0.1.x; see which sharp-runtime a CNA build uses. The check compares versions, not commits, so it cannot tell sharp-runtime’s v0.1.0 tag from its later next commits, which still declare 0.1.0; the 0.1.0 changelog records the exact commit verified with the release (c20373bae5be1f02d1fe2fa33c4cbba8ad05e4a0, tag v0.1.0). For alpha.1 nothing was checked; the “Dependency pins” part of its changelog entry in CHANGELOG.md records the revision it was developed against:
sharp-runtime 625476d5b5fff5fa89f392c3c9af8638ff237692 (develop, 2026-08-19)
To rebuild alpha.1 against that recorded sibling, check the commit out in a separate worktree and point the option at it, instead of moving the sibling directory. The following commands are illustrative and were not executed:
git -C sharp-runtime worktree add ../sharp-runtime-alpha1 625476d5b5fff5fa89f392c3c9af8638ff237692
cmake -S cna -B cna/build -DCNA_SHARP_RUNTIME_ROOT="$PWD/sharp-runtime-alpha1"
The third-party submodules need no such step. The gitlinks of third_party/SDL, third_party/SDL_mixer, third_party/draco and vendor/googletest are identical at alpha.1, at 0.1.0 and at the snapshot; the snapshot no longer has the third_party/SDL_image submodule, which nothing in CNA used. So git submodule update --init selects the same third-party revisions for every row of the table above. This was checked with git ls-tree at the three commits.
What changed since 0.1.0, at a glance
The table lists the changes a reader is most likely to notice between the release and the documented snapshot. Every number is measured at the two revisions, and every claim is defined precisely on the page it links to. Test figures are static source counts, not pass results.
| Area | 0.1.0 release | Snapshot 3b43bd86 | Where |
|---|---|---|---|
| Renderers | 14 public identities over 12 families | 10 public identities over 8 families; SDL_GPU is the modern native path and the default on Windows, macOS and iOS (not yet qualified there); every other native host defaults to OPENGLES3. A retired name is refused at configure time and at run time | Renderers |
| GPU feature layer | Renderer-internal compute, storage, indirect-draw and GPU-timer support behind capability answers | None: that layer is gone end to end, and GraphicsCapability has 17 members instead of 19 | Capability reporting |
| What a program links | Most programs linked every subsystem (avatar catalog, Guide, glTF, media, …) | A program links only the subsystems it calls; new options CNA_ENABLE_GAMER_SERVICES and CNA_OPTIMIZE_FOR_SIZE; SDL3_image removed. C++ ABI break: rebuild C++ consumers | Link boundaries and binary size |
| Native C ABI | 0.46.0, 3,210 routes | 0.50.0, 3,212 routes, generated from a declarative specification; release gate still “Not ready” | Experimental C API |
| Renamed API | GraphicsBackendCategory / GraphicsBackendMaturity | GraphicsRendererCategory / GraphicsRendererMaturity (C: cna_graphics_renderer_*); GetShaderDialectEXT() returns the public CNA::ShaderDialectEXT | Names that changed |
| Third-party sources | Upstream FNA3D 3240147 and MojoShader 6333f74, patched at configure time (1 FNA3D and 128 MojoShader patch files); SDL cbe3fbe9 with two Vulkan patches on every build; ENet 1.3.17 | FNA3D and MojoShader from CNA’s forks libcna/FNA3D and libcna/mojoshader at pinned commits, nothing patched at configure time; SDL 86296ac8 with five platform-specific patches; ENet unmodified upstream master; configure checks the vendored and fetched sources against their pins | Building CNA |
new PresentationParameters() | 800×480 windowed (FNA’s defaults) | XNA’s defaults: a 0×0 full-screen back buffer; CNAEXT PresentationParameters::CreateWindowedEXT(w, h) for a device built without a GraphicsDeviceManager (games are unaffected) | Tutorial 131 |
| Declared maturity | WEBGPU Experimental | WEBGPU Supported and in CI | Declared maturity |
| Content | Every reader registered eagerly | Readers declared, installed per family on first load; the Content Pipeline also compiles sprite fonts, cube and volume textures, effects, sounds, songs and videos to XNB | Content Pipeline |
| Avatars | Catalogs v1 to v3 | Catalog v3 is the only built-in catalog (revision 5), with description format 3; the catalog is now the cna-avatar-assets submodule | Gamer Services & Avatars |
| C# binding | CNA.NET admitted 0.46.0 | CNA.NET admits exactly 0.47.0 and builds against an earlier next commit; it consumes neither the release nor this snapshot | CNA.NET |
| Tests (static source counts) | 813 files, 11,386 definitions | 900 files, 11,927 definitions (same counting method) | Verification |
| CI workflow files | 18 (24 jobs) | 18 (25 jobs; 16 files run automatically; no C API build, no Android job) | Verification |
The renderer narrowing is the largest single change to what a downstream project can select. Do not carry CNA_GRAPHICS_RENDERER values from 0.1.0 across without checking them against the 10 current identities.
What 0.1.0 changed since alpha.1
For readers coming from the first pre-release. Measured at the two tags with the same methods; 3,709 commits lie between them.
| Area | alpha.1 | 0.1.0 |
|---|---|---|
| Renderers | 50 public identities over 46 implementation families | A curated set of 14 identities over 12 families |
| Platform implementations | 4, including SDL2 | 3: SDL3 (the one windowing platform, reaching Windows, X11 and Wayland through SDL’s video drivers), HEADLESS and TERMINAL |
| Audio implementations | 3, including SDL2 | 3: SDL3, NULL and native ALSA with CNA’s own mixer |
| Content | Read-side XNB loader with 50 built-in readers | 61 built-in XNB readers, plus a build-time Content Pipeline (cna-content) that writes CNA’s .cnb container and XNB (including LZX) |
| Development tools | None | Optional Diagnostics (CNA_DIAGNOSTICS=OFF|STATS|FULL) and Inspector modules |
| XNA API representation | Everything except Framework.Design | 331 of 331 public types and 3,627 of 3,627 documented runtime members represented (representation, not behaviour) |
| Native C ABI | 0.7.0; the final library could not compile | 0.46.0, a buildable library |
| Gamer Services | Local persistence only | Local offline profiles plus an optional self-hosted server for accounts, friends, leaderboards and relayed online sessions |
| Sibling versions | Recorded only | Required and checked at configure time |
| Tests (static source counts) | 568 files, 8,263 definitions | 813 files, 11,386 definitions |
Semantic Versioning before 1.0
CNA follows Semantic Versioning 2.0.0. The alpha.1 pre-release had lower precedence than the final 0.1.0 that followed it. During the 0.y.z phase, minor releases may change the API; pre-release identifiers communicate increasing release maturity, not an ABI guarantee. The snapshot above has not been given a new identifier: until a tag is created, the version 0.1.0 and the commit hash together are the only identity it has, and the version alone is ambiguous.
Reading the product version
The root project(CNA VERSION 0.1.0) and CNA_VERSION_PRERELEASE (empty since 0.1.0) are the build source of truth. CMake generates CNA/Version.hpp in the build tree.
#include "CNA/Version.hpp"
static_assert(CNA_VERSION_MAJOR == 0);
static_assert(CNA_VERSION_MINOR == 1);
static_assert(CNA_VERSION_PATCH == 0);
static_assert(!CNA::isPreReleaseVersion());
std::string_view version = CNA::getVersionString(); // "0.1.0"
std::string_view label = CNA::getVersionPreRelease(); // "" (alpha.1 built "alpha.1")
The generated header also provides CNA_VERSION_PRERELEASE, CNA_VERSION_STRING, and constexpr major/minor/patch accessors. Because it is generated, use the configured build's include directories rather than copying the template into a consumer. Both the 0.1.0 release and the development snapshot produce the values above; alpha.1 produced "0.1.0-alpha.1".
Product version versus C ABI
The experimental native C interface declares its own ABI identity, and that identity moves independently of the product version: 0.7.0 at the alpha.1 tag, 0.46.0 at the 0.1.0 release and 0.50.0 at the documented snapshot 3b43bd86 (and already at the previous one, c6dec91f), while the product version moved only once, from 0.1.0-alpha.1 to 0.1.0. Several of the minor steps in between were incompatible changes; the ABI history table is on the C API page.
At the alpha.1 tag the C library could not be produced at all: its C renderer table had 49 entries against the canonical 50, and a deliberate static_assert stopped compilation, so 0.7.0 identified a checked-in contract rather than a consumable binary. That blocker was resolved before 0.1.0. No CNA CI job builds the C library; CNA’s own campaigns build and test it locally (on Linux, and cross-compiled for Windows under Wine at this snapshot), and the C# binding CNA.NET builds and uses it on Linux. Treat both version numbers as identities of a source contract, not as evidence of a shipped binary.
#include <CNA/C/abi.h>
uint32_t runtime_abi = cna_get_abi_version();
if (runtime_abi != CNA_ABI_VERSION) {
/* refuse or use an explicitly supported compatibility path */
}
See Experimental C API for the measured source scope, the package design, the version history and the boundary with external language bindings.
Exact source boundary for this site
The alpha.1 edition of this site audited changes from ae0be4b5211957efaef60f2f23627ae5a9ddda23 through the alpha.1 tag; later editions audited the ranges up to earlier development snapshots. This edition audits the range from the previous snapshot (c6dec91f, 812 commits after the v0.1.0 tag) to 3b43bd8687ed46523d873f9bec4b32bd8481dcb5, 136 commits with no release in between; the edition before it audited c1c316b9 (22 commits before the tag) to c6dec91f, which included the release commit. Claims come from the final tree's implementation, CMake configuration, headers, registries and tests. Repository plans and changelog entries are discovery aids, not overrides for contradictory code.
Consumer projects (the samples, demos, showcase games and language bindings) are evidence only for their own pinned revisions, not for any CNA revision described here.
Deep dives on this topic
Long-form pages that explain the exact semantics, invariants and evidence behind this subject.
- CNA and XNA 4.0: what the compatibility promise covers — What CNA translates and cannot load, which reference settles a disputed XNA question, what CNA deliberately is not at snapshot 3b43bd86, and its Ms-PL licence and FNA provenance.
- Project records as evidence: plans, ledgers, versions, handoffs and re-audits — How to use and write CNA's plans, handoffs, audits and gates as evidence: roles, stable task IDs, executable ledgers, version coordinates, defect-ledger rules and documentation re-audits.