Repository map

CNA snapshot 009d40f5  ·  Development › Repository & Ownership  ·  source links pinned to 009d40f5

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 009d40f5: 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/, Sdl2/, Win32/, X11/, Wayland/, Headless/, Terminal/) beside Common/ and the pieces only the Unix desktop backends share (Xkb/, Freedesktop/, Posix/, Linux/), 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 _.
• One documented ownership exception. The GDI renderer compiles eight software-module CPU-2D translation units into its own archive; their physical owner stays renderers/software. Every other file's directory is its CMake owner.
• Renderer families need not have every subdirectory. Fifteen of the 21 families have a tests/ directory (and so do both shared helpers); freedirect, gdi, headless, portablegl, sdl-renderer 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 904 C++ test sources discussed below.

Public, Internal and private headers

"Public" is a tree-shape word at this snapshot, not an export mechanism. The C++ framework has no install() rules, every module publishes its whole include/ directory PUBLIC, 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 808 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 904 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 path 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. The HEADLESS configuration additionally proves that renderer-neutral graphics needs no native graphics SDK.
• 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.
• Include reachability: modularization/tools/check_include_reachability.py checks that every "CNA/..." or "Microsoft/..." include in a module translation unit resolves through a module graph written into the script itself. At this snapshot that graph is out of date (it lists 14 of the 22 declared framework modules; platform, diagnostics, content-pipeline, phone, c-api, design, inspector and video-ffmpeg are absent) and no CMake rule, test or workflow runs the script, so it is a manual aid rather than a gate that keeps this map true.
• 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.