Releases & Versioning

Latest tagged release: 0.1.0-alpha.1  ·  tagged 20 August 2026  ·  documented here as well: development snapshot c1c316b9 (9 October 2026, branch apple/m4-stabilization)

The first tagged release

The leading v belongs to the Git tag. The product version reported by CMake and C++ is 0.1.0-alpha.1 without it. Browse the immutable tagged source or its release changelog. There is no GitHub Release object for it (or for anything else): the repository publishes Git tags only (v0.1.0-alpha.1 and an audit marker, audit-2026-07-complete).

The post-alpha.1 development snapshot

Development did not stop at the tag. The site’s reference revision is a commit on the apple/m4-stabilization branch, chosen so that every claim can be checked against one immutable tree:

Because the version string did not change, CNA::getVersionString() cannot tell the two revisions 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 c1c316b9; where they say “alpha.1” they mean the tag.

What "7,463 changed paths" counts

The 7,463 figure comes from git diff --shortstat v0.1.0-alpha.1 c1c316b9 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 3,212 additions, 1,483 deletions, 2,704 modifications and 64 renames. git diff --no-renames --name-status counts every rename as a deletion plus an addition and lists 7,527 records (3,276 / 1,547 / 2,704). 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.

How to obtain each revision

Layout, system packages and the sibling checkouts are the same as in Getting Started and Building; the only difference between the two rows above is which CNA and sharp-runtime branch you check out.

Which sharp-runtime revision goes with alpha.1

CNA's build does not pin sharp-runtime. The root CMakeLists.txt adds whatever checkout CNA_SHARP_RUNTIME_ROOT points at (default ../sharp-runtime); see which sharp-runtime a CNA build uses. For the tag, the "Dependency pins" part of the [0.1.0-alpha.1] entry in CHANGELOG.md records the revision the release was developed and verified against:

sharp-runtime  625476d5b5fff5fa89f392c3c9af8638ff237692  (develop, 2026-08-19)

The changelog calls this record a stopgap: it documents the pin but does not enforce it. It also announces a configure-time check or a submodule as the real mechanism. Neither exists at c1c316b9. To rebuild alpha.1 against its recorded sibling, check that 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_image, third_party/SDL_mixer, third_party/draco and vendor/googletest are identical at the tag and at c1c316b9. So git submodule update --init selects the same third-party revisions for both rows of the table above. This was checked with git ls-tree at both commits.

What changed since alpha.1, at a glance

The table lists the changes a reader is most likely to notice. Every number is measured at the two revisions (alpha.1 tag and snapshot c1c316b9), and every claim is defined precisely on the page it links to. Test figures are static source counts, not pass results.

The renderer curation is the largest single change to what a downstream project can select. Do not carry alpha.1 CNA_GRAPHICS_RENDERER values across without checking them against the 14 current identities.

Semantic Versioning before 1.0

CNA follows Semantic Versioning 2.0.0. The alpha.1 suffix has lower precedence than a final 0.1.0. During the 0.y.z phase, minor releases may change the API; alpha, beta and release-candidate 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 pre-release label alpha.1 and the commit hash together are the only identity it has.

Reading the product version

The root project(CNA VERSION 0.1.0) and CNA_VERSION_PRERELEASE 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-alpha.1"
std::string_view label = CNA::getVersionPreRelease(); // "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 alpha.1 and the development snapshot produce the values above.

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 snapshot c1c316b9, while the product version stayed 0.1.0-alpha.1 throughout. 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 is resolved in the snapshot’s source (the C renderer table and the canonical set now agree). No CNA CI job builds the C library; CNA’s Apple campaign built and tested it on a physical Mac mini M4, 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 (which pin an older ABI, 0.21.x, independently).

Exact source boundary for this site

The alpha.1 edition of this site audited changes from ae0be4b5211957efaef60f2f23627ae5a9ddda23 through the resolved tag commit above. This edition additionally audits the range from that tag to snapshot c1c316b9c7a846ce8002809c151fcd1af14942c9. In both, 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; CNA’s own CHANGELOG.md is known to omit several of the changes listed above (it has no entries for Diagnostics, Inspector or the content pipeline).

Consumer projects (the samples, demos, showcase games and language bindings) are evidence only for their own pinned revisions, not for either CNA revision described here.