Repository map

CNA snapshot 3b43bd86  ·  Development › Repository & Ownership  ·  source links pinned to 3b43bd86

CNA is a module-oriented monorepo. Production code lives under modules/, build policy under cmake/, shared fixtures and cross-module suites under tests/, and generators, audits, launchers and harness sources under tools/ and scripts/. This page is the map of that layout at snapshot 3b43bd86: what each directory holds, how a module directory is shaped, which headers are public, Internal or private, what is generated, where the vendor boundaries run and which tests belong to whom. Read it before opening a source file you did not write; the lookup "which part of CNA owns this behaviour?" is a separate page, Source ownership.

Top-level map

Every row is a directory (or file group) at the repository root, with the number of files Git tracks in it at this snapshot. The right-hand column says when you would edit there. Counts describe tree shape, not importance.

Physical module shape

modules/<name>/
├── CMakeLists.txt       target and dependency declaration; collects its own sources
├── include/             public and cross-module headers, spelled as consumers include them
│   ├── Microsoft/...    XNA-shaped API (Microsoft/Xna/Framework/..., Microsoft/Devices, Microsoft/Phone)
│   └── CNA/...          CNA-owned surface; CNA/Internal/... holds cross-module internal contracts
├── src/                 implementation and module-private headers
│   ├── Xna/             XNA API implementation
│   ├── Internal/        CNA::Internal engine parts
│   └── CnaExt/          CNAEXT extension surfaces (single-area modules stay flat)
├── tests/               GoogleTest sources mirroring the namespace path
├── examples/            demos and example programs, registered by the module's own CMake
└── benchmarks/          only diagnostics and inspector have one

The include tree mirrors the namespace-facing path, so #include "Microsoft/Xna/Framework/Graphics/Texture2D.hpp" resolves from modules/graphics/include and the spelling is identical wherever a consumer sits. A module's src/ uses the area convention Xna/, Internal/, CnaExt/ (see modules/graphics/CMakeLists.txt for the globs); the platform module instead gives every implementation its own directory (Sdl3/, Headless/, Terminal/) beside Common/ (the portable pieces more than one of them shares), and the audio module separates Platform/ (devices) from Backend/ (mixers). The CNA umbrella composes module targets as an INTERFACE library; it does not compile into one giant library, and cmake --build <dir> --target CNA is not a buildable target (the umbrella and its link closure).

• How a module becomes a target. modules/CMakeLists.txt defines cna_add_module(target alias sources...): a STATIC library cna_<name> with the alias CNA::<Alias>, linked PUBLIC to cna_build_config and publishing that module's own include/ as its PUBLIC include root. Sources are collected with file(GLOB … CONFIGURE_DEPENDS) from the module's own src/ (the graphics core globs its Xna, Internal and CnaExt areas, a renderer family globs only its own src/*.cpp, not recursively), so adding a .cpp there needs no CMake edit. The one module that lists its sources by hand is c-api.
• Naming exceptions. gamer-services, net and video-ffmpeg call add_library directly (CNA_GamerServices, CNA_Net, cna_video_ffmpeg); core also defines the header-only cna_core_headers (CNA::CoreHeaders) that math, storage and phone link instead of the archive; content-pipeline is cna_content_pipeline with the alias CNA::ContentPipelineBuild; c-api is cna_c_api, a shared library (static under Emscripten); each renderer family is cna_renderer_<family> with - replaced by _.
• Location is ownership. Every file's directory is its CMake owner. The shared renderer helpers are deliberate sharing inside their own directories: common/mojoshader (cna_renderer_mojoshader_effect, the compiled-effect runtime that FNA3D and the compiled-effects options link) and the cna_renderer_d3d9_effect sub-target inside directx9.
• Renderer families need not have every subdirectory. Six of the 8 families have a tests/ directory (and so does the shared helper); headless and stub keep their tests as example programs under examples/.

The 23 directories and their targets

The direct CNA link edges below were read from each module's CMakeLists.txt (PUBLIC unless marked); sharp-runtime components and third-party libraries are left out. "Umbrella" means the target is one of the parts of the CNA INTERFACE library in modules/CMakeLists.txt. The three intentional static-archive cycles (graphics and input, audio and media, graphics and the selected renderer) are why some edges are PRIVATE.

Rows for graphics and renderers hide the interesting part: the graphics core links every selected family privately (the factory edge) and each family links the graphics core back (the reverse edges), which is why static link order is a declared invariant rather than an accident. Both halves are traced in the CMake architecture chapter. The generated module index lists the same directories with header, source and test-file counts and entry-point headers; its "test files" column counts every file under tests/, not the 900 C++ test sources discussed below.

Public, Internal and private headers

"Public" is a tree-shape word at this snapshot, not an export mechanism. Every module publishes its whole include/ directory PUBLIC, the opt-in installed C++ SDK (CNA_INSTALL_CXX, cmake/InstallCxx.cmake) installs those same whole trees, Internal headers included, and nothing stops a target that links a module from including a header under CNA/Internal. The classes below are conventions enforced by review and by the gates in What keeps this map true.

The generated public header index lists 718 non-Internal headers under include/CNA and include/Microsoft in 21 modules; it says nothing about which of them are supported API.

Subsystem families

Group modules by the question they answer and the boundary a change crosses, not by directory name. Each row is a family of modules that usually change together; the last column states the ownership fact a reviewer should hold in mind. For the per-object lifetime rules behind these statements see Ownership and lifetime master map and What a human maintainer inherits.

How to find the owner

1. Find the public symbol's declaration with a search under the module include/ directories, for example rg -n "class SoundEffect\b" modules/*/include. The directory you land in is the candidate owner.
2. Find the out-of-line definition, the constructor and every place the state is mutated in that module's src/. A static XNA API (Keyboard::GetState, StorageDevice) may reach an ambient platform rather than a context you can see.
3. Trace factory and registry creation instead of assuming the directory is selected. For a renderer that means the identity map in cmake/RendererRegistry.cmake, the family's *RendererDescriptor.cpp and the generated CnaRendererRegistry.generated.cpp; for a platform, PlatformFactory; for audio, the compiled-in device and mixer.
4. Search the focused tests in the owning module's tests/ first, then the conformance and integration tests that name the symbol, then the renderer-family example programs.
5. Read the module's CMakeLists.txt before crossing a boundary: which targets it links, whether the link is PUBLIC or PRIVATE, and whether the module is entered conditionally.
6. Confirm the answer against Source ownership, the module dependency map and the generated module index and public header index, which give source-pinned entry points.

Generated and checked-in generated files

Two different things are called "generated". Some files are produced into the build tree during configure or build and never committed; others are committed but must stay derivable from their sources, and a gate fails when they drift. Before committing a change to either kind, find the generating rule and reproduce the output from clean input.

Third-party and vendor boundaries

Four mechanisms bring outside code into a CNA build, and each has a different rule for how you touch it. The general rule: third_party/ and vendor/ are external. CNA's build policy (warnings, sanitizers, debug-information and linker options) is attached only to targets whose source directory lies inside the repository and outside those two trees, so a change there is dependency maintenance, not a CNA edit.

Where tests live and who owns them

Test ownership follows source ownership. A module's unit tests live in that module's tests/, mirroring the namespace path, and are compiled into a per-module object group; renderer-family behaviour is exercised mostly by example programs in the family's examples/; only genuinely cross-module material sits in the top-level tests/. The counts follow the table; how the sources are assembled into executables is described on Test architecture.

The 900 C++ test source files counted by the site method (every .cpp under a tests/ or test/ directory, vendored code excluded) are distributed as follows, recomputed by owning directory from the Git tree at this snapshot. The figure is a source inventory, not an executable case count and not a pass result.

What keeps this map true

Most of the layout is enforced mechanically, so a map that disagrees with the tree is the map's fault. These are the gates to run or read when you move a file, add a module, or add a dependency edge.

• Source-partition validator in modules/CMakeLists.txt: every .cpp or .mm under modules/ must sit in a declared module's src/, tests/, examples/ or benchmarks/ tree (lists _cna_framework_modules and _cna_renderer_modules); a legacy root src/ or include/ fails. Moving a file between directories is a build-ownership change, not a rename.
• Minimal-link probes in cmake/Tests/ModuleProbes.cmake: fifteen tiny consumers of one module alias each, paired with ModuleLinkClosure_* tests that run scripts/check_module_link_closure.py over the generated link line and fail when a forbidden archive or library appears. A HEADLESS-only configuration additionally proves that renderer-neutral graphics needs no native graphics SDK, and the LinkFootprint_* gates in cmake/Tests/LinkFootprint.cmake check that a program links only the subsystems it uses.
• Identity and discipline scripts: scripts/check_renderer_identities.py holds the CMake identity list, the registry map, the C++ enumeration and the C ABI header to one canonical table; scripts/check_renderer_target_discipline.py and scripts/check_runtime_renderer_discipline.py keep families from reading global scalars and keep renderer-specific decisions behind descriptors.
• Configure-time SDL audits (the platform ratchet, the non-production SDL audit and the hot-path lint) keep SDL inside the platform module; see CMake architecture: gates that run at configure time.