Generated references
Evidence basis: source-verified at the pinned commit. Claims on this page were checked by reading the CNA source at commit 009d40f5; unless a sentence says otherwise, nothing here was built or executed. Describes the generator and the pages it writes as they exist at the snapshot; the generated pages are syntactic inventories and establish no behaviour or test result.
These inventories are generated from the Git objects of the pinned CNA commit (009d40f5, recorded in cnahead). They reduce drift by giving every count on the site one mechanical source, and they answer “where is it?” quickly, but they do not replace the reviewed explanations: each one is a syntactic scan that locates declarations, files and registry entries and establishes no behaviour, build success or test result.
The five generated indexes
| Index | Answers | Derived from | What it cannot tell you |
|---|---|---|---|
| Module index | Which physical production modules and which renderer directories exist; for each, its header, source and test-file counts and source-pinned entry points, with a link to its internals page where one exists. | The directory tree of the pinned commit (every directory under modules/, and every family under modules/renderers/; a directory that owns a src/ is an implementation family, and one that does not is a shared helper). | Architectural importance: a module with few headers can own a lot of behaviour, and header counts include Internal/ headers. A module without an internals page has simply not had a deep tour. |
| CMake option index | Every cache option or variable with its kind, default or value, description and declaring file. | A scan of every CMakeLists.txt and .cmake file for option(), cmake_dependent_option() and set(... CACHE ...) declarations. | Conditional defaults, values rewritten after declaration, and which combinations are valid. Read the linked CMake logic and the selection axes before relying on a value. |
| Test target index | Test-related executables and CTest registrations, each with its declaring CMake file, and the number of C++ test source files. | A scan for add_executable and add_test declarations that are test-shaped, and a count of .cpp files under tests/ or test/ directories. | What one configured build contains: generator expressions and helper functions create further tests at configure time and configuration filters drop others. Confirm with ctest --test-dir <build> -N. A declaration is a registration, not a result. |
| Public header index | Headers under include/CNA or include/Microsoft, outside Internal, grouped by module, each source-pinned. | The file list of the pinned commit. | Which headers are supported API: “public” is a tree-shape term here and includes the whole XNA-shaped surface. Export macros and install rules remain authoritative, and the C ABI headers are versioned separately. |
| Selection axes index | The 25 renderer identities with their C ABI values, C++ enumerators and implementation families (21), the 7 platform implementations and the 4 audio implementations, with the reserved values that are refused. | The identity list, the canonical ABI table and the identity-to-family map of the CMake registries, plus the platform and audio selection files. The generator refuses to write the page if those sources disagree with one another or with the site's canonical counts. | Whether a given combination builds or runs on a host. The combination rules are in the selection files and on Renderer selection internals. |
Generation contract
generate_dev_reference.py (in the scripts directory of the libcna.com repository) reads cnahead, and lists the tree and reads files from the Git objects of that commit with git ls-tree and git show in the CNA repository (by default a sibling directory ../cna, overridable with CNA_REPO). It never checks out the revision and never touches a branch, index or working tree, so it cannot overwrite an in-progress CNA checkout; if the pinned commit is not present in that repository it stops instead of guessing. Each page is rendered through the same chrome as the hand-written Development pages (site_dev.py), so a generated page has the same sidebar, related-pages block and evidence box, plus a Generated page notice.
python3 ./scripts/generate_dev_reference.py # writes the five pages under development/reference/
bash ./scripts/validate_all.sh # then the site validatorsThe five pages are outputs, not sources: change them through the generator, and only edit the generated HTML by hand to fix the generator's own output. The index page you are reading is authored. Regenerate when the pin moves or when the generator itself changes; on an unchanged pin and generator the output does not change. The full procedure for moving the pin, including the order in which to regenerate and what to review in the diff, is on Maintaining these pages.
Reading a generated page well
- Treat a count as tree shape. A count says how many files or declarations matched a pattern, not how much behaviour they hold or whether a build includes them.
- Follow the link to the source before believing a row. Every row links to the declaring file at the pinned commit; the defaults and conditions are in the file, not in the table.
- Use the index to find, and the page to understand. Each index links to the reviewed pages that explain what it locates: the Repository map, the Build system pages, the Testing handbook, the change map and the Internals pages.
- Do not copy a number out of a generated page into prose. Canonical counts live in
data/current-facts.jsonand are checked against the pages; prose that repeats a generated number goes stale silently.
Related: Maintaining these pages for the pin policy and the checks, and Getting started as a maintainer for a first tour of the code these indexes point into.
Related pages
The same subsystem is explained at four altitudes. These are the neighbouring pages at each one.
- Architecture
- Physical module dependency map
- Internals
- Internals
- Maintainer workflow
- Maintaining these pages · Change map
- Tests and validation
- Testing handbook