Contribute to CNA

Getting started

Step 1 — Clone CNA and initialise submodules

git clone -b apple/m4-stabilization https://github.com/libcna/cna.git
cd cna
git submodule update --init

This populates third_party/SDL, third_party/SDL_image, third_party/SDL_mixer, third_party/draco and vendor/googletest (needed while tests are on). SDL3 is built from source by CMake — no system SDL packages are required. The non-recursive form is correct: recursion only pulls codec submodules CNA does not use.

Step 2 — Clone sibling repositories

CNA always requires sharp-runtime as a sibling directory next to cna/, and it must be sharp-runtime's apple/m4-stabilization branch — its main and develop lack components CNA now requests. Two more siblings are needed only by the GL renderers: easy-gl (with meta-gl) for the three GL-profile identities, which includes the Linux default OPENGLES3.

parent/
├── cna/
├── sharp-runtime/   # always required, branch apple/m4-stabilization
├── easy-gl/         # OPENGLES3, OPENGL33, WEBGL2
└── meta-gl/         # needed by easy-gl

Clone them at the same level:

git clone -b apple/m4-stabilization https://github.com/libcna/sharp-runtime.git
git clone https://github.com/libcna/easy-gl.git
git clone https://github.com/libcna/meta-gl.git

Step 3 — Build with EasyGL

cmake -S . -B build -DCNA_GRAPHICS_RENDERER=OPENGLES3
cmake --build build --target CnaTests

CNA is an interface umbrella, not a standalone build target; build CnaTests, a focused module target such as CnaMathTests, an example, or your consumer target. CNA accepts 14 renderer identities across 12 implementation families. A normal configure selects one through CNA_GRAPHICS_RENDERER; an opt-in CNA_GRAPHICS_RENDERERS list can link several compatible families for pre-device runtime selection. A name outside the 14 is a configure-time error. See the Building documentation for the full inventory and platform gates.

Step 4 — Run the tests

./build/CnaTests                        # from the repository root: the tests preset's authoritative way to run the aggregate suite
ctest --test-dir build -N               # list what this configuration registered (an unfiltered ctest needs a full build first)

The snapshot's source tree has 813 C++ test files and 11,380 statically discoverable GoogleTest-family definitions (781 files contain at least one; alpha.1 had 568 and 8,263). A further 781 standalone examples/**/*_test.cpp pixel programs are not in those figures. What reaches CnaTests and CTest depends on renderer set, platform, audio implementation, host and options. Run the configuration you changed and include its configure command, ctest -N inventory and failing output in a report. On a headless box, launch CTest under a virtual display (xvfb-run -a ctest ...).

Step 5 — Run one module, or run tests safely

Each module has a focused test executable built from the same objects as CnaTests: CnaMathTests, CnaCoreTests, CnaAudioTests, CnaContentTests, CnaContentPipelineTests, CnaGraphicsTests, CnaGraphicsExtTests, CnaStorageTests and 14 more (22 in all). They are iteration targets, not extra CTest entries:

cmake --build build --target CnaMathTests
./build/CnaMathTests --gtest_filter='Vector2Test.*'      # run from the repository root

Window-creating GPU tests no longer default to your live desktop. CNA_TEST_DISPLAY is empty by default, so those tests inherit the DISPLAY of whoever launches them; naming :0 needs -DCNA_TEST_ALLOW_LIVE_DISPLAY=ON. To run them on a private headless compositor with the real GPU, use tools/platform/run_gpu_tests_private.sh build -L Parity. A large binary can exhaust memory in one process (the whole CnaTests could not run on WEBGPU that way), so tools/tests/run_gtest_bounded.sh shards a GoogleTest binary, reports a signal-killed shard as KILLED and fails instead of reporting a partial pass. Tutorial 160 walks through all of it, and Tutorial 161 shows how to diff a renderer against the XNA oracle corpus.

Repository structure

The CNAEXT marker

Methods and types annotated with the CNAEXT macro (from CNA/CNAHelper.hpp) are not part of the XNA 4.0 public API. They exist purely to support C++ idioms and integration patterns. In a normal build the macro expands to nothing; under the CNA_STRICT_XNA_API purity mode it expands to [[deprecated]], so a strict compile with -Werror=deprecated-declarations fails if code calls an extension. That strict check is run for the Microsoft::Devices and Sensors surface today. Examples:

• Iterator support — begin() / end() on collections to enable range-for loops
• GetTypeName() — runtime type name helper for debugging
• RAII helpers and move constructors that have no equivalent in managed C#
• Engine-layer additions, conventionally named with an EXT suffix (for example GetGraphicsRendererType() or ShowAchievementsEXT())

The authoritative reference for the XNA 4.0 public API surface is FNA (C#). When in doubt whether a method belongs to the XNA API, check the corresponding FNA class. If it is present there without modification, it belongs in CNA without the CNAEXT marker. If it is a C++-only addition, mark it CNAEXT.

What needs work

Below are the most impactful contribution opportunities, grouped by area. Any of these would be a meaningful addition to the project. Each was checked against the snapshot's source or CNA's own records; items taken from CNA's notes say so.

Adding a renderer

CNA's own candidate list is explicitly research, not a roadmap: nothing in it is planned or authorised, and each candidate would need a fresh explicit owner instruction, its own plan file and its own acceptance criteria. If a proposal is accepted, the mechanical part is that all of these must agree, and a script holds them to each other:

• the GraphicsRendererType enumerator and its canonical name, the CMake selector and compile definition, the selected target and factory branch, and the platform and dependency gate;
• the runtime registry and the C ABI value table — C ABI values are stable and sparse, gaps in the numbering stay reserved and are never reused, and the next new identity takes value 52;
• scripts/check_renderer_identities.py (registered as the CTest RendererIdentityRegistry) fails when the registries disagree, and a name outside the 14 public identities is refused at configure time by name — never aliased, never a silent fallback.

A renderer also needs a declared maturity and category, a capability profile that answers honestly, its tests registered through cna_register_renderer_test, and evidence at its real scope: at minimum the shared parity fixtures (cna_register_parity_fixtures()) and pixel-readback tests, and an honest statement of what the oracle corpus does and does not say about it. See Verification & Known Issues for how evidence is labelled and the Renderers page for the current set.

Code style

• C++23 throughout. CNA needs CMake 3.20 or newer and a C++23 compiler with <format> (libstdc++ 13, a current libc++, or MSVC 2022). CMake does not check compiler versions; CI exercises GCC 14, AppleClang, MSVC and MinGW-w64, so older compilers are untested. Use modern C++ features freely — structured bindings, ranges, concepts — but keep readability first.
• API shape is fixed. The Microsoft::Xna::Framework public API mirrors XNA 4.0 exactly. Do not rename, remove, or add overloads to public methods without a compelling reason backed by FNA precedent.
• Properties become getter/setter methods. C# public int Width { get; set; } becomes intcs getWidthProperty() const and void setWidthProperty(intcs value) in C++.
• Use sharp-runtime types. Use intcs, bytecs, Single, String, events, and interfaces from sharp-runtime to match C# semantics. Avoid raw int or float at the public API boundary.
• No extra runtime dependencies. CNA's dependency set is deliberately small and mostly vendored or submoduled — SDL3 (plus SDL_image and SDL_mixer), sharp-runtime, and the GL renderers’ sibling easy-gl (with meta-gl), alongside in-tree enet, cgltf, stb, dr_libs and the fetched wgpu-native and FNA3D. Do not introduce new third-party libraries without prior discussion.
• Mark non-XNA additions as CNAEXT. Any method or type added purely for C++ convenience must carry the CNAEXT macro so that API coverage tooling and the strict purity check stay accurate.
• Tests state their oracle. A test that compares with real XNA, FNA, a golden image or only its own assertions says which in its header, uses tolerance 0 unless a written reason says otherwise, and never widens a tolerance to turn a comparison green.

License and attribution

CNA is licensed under the Microsoft Public License (Ms-PL). All contributions must be compatible with the Ms-PL. By submitting a pull request you agree that your contribution will be distributed under the same license.