Command-Line Tools

CNA snapshot 3b43bd86 · content pipeline, .cnb and Inspector tools

ℹ

A catalogue, read from the source. This page lists the content, inspection and Inspector executables that CNA’s CMake defines at snapshot 3b43bd86 (the tool targets and their CMake files are unchanged since c1c316b9): what each does, its options as printed by its own usage text, and the build target that produces it. Of the tools in the first table only cna_tool_gltf_to_cnj exists in the alpha.1 tag; the others are new. Test harnesses and dump utilities are listed at the end. The content-pipeline workflow itself (Importer → Processor → Writer, formats, incremental builds) lives on the Content Pipeline page and is not repeated here. We did not build or run these tools for this page; usage and options are quoted from the sources.

The tools at a glance

Executable	CMake target	What it does	Needs a window or GPU?
`cna-content`	`cna_content_tool`	The build-time content compiler: `build` and `clean`; source assets to `.cnb` or `.xnb`.	No
`cna_tool_cnb_info`	`cna_tool_cnb_info`	Inspect and validate a compiled `.cnb` asset.	No
`cna_tool_source_to_cnb`	`cna_tool_source_to_cnb`	Compile one source file (image, WAV, DDS, song/video metadata) to `.cnb`.	No
`cna_tool_cnj_to_cnb`	`cna_tool_cnj_to_cnb`	Compile a `.cnj` document and its sidecars to one `.cnb`.	No
`cna_tool_gltf_to_cnb`	`cna_tool_gltf_to_cnb`	Compile a glTF 2.0 file straight to `.cnb` assets.	No
`cna_tool_gltf_to_cnj`	`cna_tool_gltf_to_cnj`	Convert glTF 2.0 to a `.cnj` Model/AnimationClip (the alpha.1 tool).	No
`cna_tool_xnb_interop_fixtures`	`cna_tool_xnb_interop_fixtures`	Write CNA’s generated XNB interoperability corpus and its expected-value manifests.	No
`cna-inspector`	`cna-inspector`	The Inspector browser bridge.	No (needs a running CNA app with an agent)

Building the tools

The content tools are defined unconditionally at the root of the CNA build (they are ordinary add_executable targets, not gated by CNA_BUILD_TESTS or CNA_BUILD_EXAMPLES), so any configured tree can build them. They link the CNA content layer and never construct a GraphicsDevice, so they run on a build machine with no display, GPU or sound card. Build one by target name:

cmake -S . -B build
cmake --build build --target cna_content_tool cna_tool_cnb_info cna_tool_source_to_cnb

Each executable lands in the CNA project’s binary directory (build/ when CNA is the top-level project); cna_content_tool is named cna-content through its OUTPUT_NAME. The Inspector bridge is the exception: cna-inspector exists only with -DCNA_BUILD_INSPECTOR=ON and lands in build/modules/inspector/. When CNA is brought in with add_subdirectory, the same paths are relative to the subdirectory’s binary directory.

`cna-content`

The command-line front end of the build-time content pipeline. Two verbs:

cna-content build <source-file-or-directory-or-.contentproj> -o|--output <output> [options]
cna-content clean <output-directory> [--quiet]

Content is built through Importer → Processor → Content Type Writer. --format selects the container: CNA’s native .cnb (the default) or the XNA-compatible .xnb. Importers and processors are the same for both; only the writer differs. A single source file needs an output path whose extension matches --format; a source directory needs an output directory (relative paths and logical content names are preserved). clean removes only unchanged files proven to be pipeline-owned by a valid output manifest.

Option	Meaning
`--format cnb\|xnb`	Output container. Default `cnb`.
`--config <file>`	A configuration file of per-asset overrides.
`--only-configured-assets`	Make the configuration the asset list rather than a set of overrides; a discovered source it does not name is left alone. A `.contentproj` build selects it automatically.
`--workers <1..64>`	Worker count.
`--xna-compatible`	Build with XNA-compatible behaviour.
`--xnb-platform <name>`	XNB target platform. XNA 4.0 platforms are `windows`, `windowsphone`, `xbox360`; other values (`desktopgl`, `linux`, `ios`, `android`, `windowsgl`) are extended identifiers XNA 4.0 never produced. `xbox360` is refused unless `--xnb-allow-unverified-xbox` is also given.
`--xnb-version 4\|5`	XNB container version; 5 is the XNA 4.0-era container, 4 is earlier legacy XNB.
`--xnb-profile reach\|hidef`	XNA graphics profile.
`--xnb-compress none\|lzx\|lz4`	XNB compression. `lzx` is the compression XNA 4.0 itself produced (CNA emits real, deterministic LZX; its own tests load the fixtures through a genuine XNA 4.0 `ContentManager`); `lz4` is a later-ecosystem extension refused on an XNA 4.0 target platform.
`--xnb-reader-names xna40\|portable`	Reader-name style written into XNB files.
`--fx-compiler <path>`, `--fx-compiler-launcher <program>`	The external fxc-compatible compiler used for `.fx` source, and a program to run it through such as `wine`. Resolution order: the option, then the `CNA_FXC` / `CNA_FXC_LAUNCHER` environment variables, then the path baked in by CMake, then `fxc` on `PATH`. A `.fxb` is already compiled and needs no compiler.
`--xma-encoder <path>`, `--xma-encoder-launcher <program>`, `--xma-encoder-arg <argument>`	Attach your own XMA audio encoder (CNA ships none: asking for XMA without one reports it externally unavailable). Arguments may use `{input}`, `{output}`, `{quality}`, `{loopStart}` and `{loopLength}`. Environment forms: `CNA_XMA_ENCODER`, `CNA_XMA_ENCODER_LAUNCHER`, `CNA_XMA_ENCODER_ARGS`.
`--font-directory <dir>` (repeatable)	Add a directory to the `.spritefont` font search, ahead of the platform’s own. `CNA_FONT_PATH` in the environment adds more, read after these.
`--build-configuration <name>`	The equivalent of MSBuild’s `$(Configuration)`; `Release` unless given. It is what the effect processor’s debug mode follows.
`--explain`, `--quiet`	Explain why each asset was (or was not) rebuilt; suppress output.

build/cna-content build assets -o build/content                       # .cnb output (default)
build/cna-content build assets -o build/content-xnb --format xnb --xnb-compress lzx
build/cna-content build MyGame.contentproj -o build/content-xnb --format xnb
build/cna-content clean build/content

The CMake side is cna_add_content(TARGET ... SOURCE_DIR ... OUTPUT_DIR ...), which adds a build target that runs the same executable. Its keywords are TARGET, SOURCE_DIR or CONTENT_PROJECT (alternatives), OUTPUT_DIR, CONFIG_FILE, WORKERS, FORMAT (cnb or xnb), XNB_PLATFORM, XNB_PROFILE, XNB_COMPRESS, XNA_COMPATIBLE, QUIET and CONTENT_EXECUTABLE (required when cross-compiling, because a target-platform tool cannot run on the host). The XNB_* keywords need FORMAT xnb, and a CONTENT_PROJECT refuses the keywords its project file already carries. The target intentionally runs whenever it is requested; the tool’s content-hashed manifest makes an identical run a cheap no-op.

ℹ

Two custom-compiler examples show how to write your own content compiler on the same library: cna_custom_content_compiler_example (canonical API) and cna_xna_custom_pipeline_example (written against the XNA pipeline facade). They are built when CNA_BUILD_EXAMPLES or CNA_BUILD_TESTS is on and are linked to cna_content_compiler rather than loaded as plugins.

The `.cnb` tools

Four focused executables predate cna-content or complement it. All are built in every configuration and none needs a GPU.

Tool	Usage (from its own help)	Notes
`cna_tool_cnb_info`	`<file.cnb> [--refs] [--chunks] [--quiet] [--help]`	Inspects and validates a compiled asset; every structural invariant is checked while reading, so a non-zero exit means the file is malformed and the message says how. `--refs` prints only the external asset names the file depends on, one per line, for build scripts; `--chunks` prints only the chunk table; `--quiet` reports through the exit code alone.
`cna_tool_source_to_cnb`	`<input> <output.cnb> [options]`	Headless, deterministic (no device, clock or randomness). The input kind follows its extension: `.png .jpg .jpeg .bmp .tga .gif .psd .hdr .pic .pnm` → Texture2D; `.wav` → SoundEffect; `.dds` (DXT1/3/5 or RGB888/BGR888 cube) → TextureCube; anything else with `--as song\|video` → Song/Video metadata. Options: `--name`, `--mipmaps`, `--mip-color-space linear\|srgb`, `--color-key R,G,B`, `--as`, `--stream` (Song/Video, required), `--duration-ms`, `--title`, `--frame-size WxH` and `--fps` (Video, required), `--soundtrack`, `--quiet`. An option that does not apply to the chosen kind is refused, not ignored.
`cna_tool_cnj_to_cnb`	`<input.cnj> [output.cnb] [options]`	Compiles a `.cnj` document and the binary sidecars it names into one `.cnb`. Options: `--content-root <dir>` (where sidecar references resolve; default the input’s own directory), `--name <logical>`, `--quiet`.
`cna_tool_gltf_to_cnb`	`<input.gltf\|input.glb> <outputDir> <baseName> [options]`	Compiles glTF 2.0 directly into one or more `.cnb` assets with no `.cnj` left behind, using the same glTF interpretation as `cna_tool_gltf_to_cnj` (it runs the same code). Options: `--unit-scale <f>` (default 1.0; use 0.01 for a centimetre-authored source), `--keep-cnj <dir>` (also write the intermediate `.cnj` and sidecars), `--quiet`.
`cna_tool_gltf_to_cnj`	`<input.gltf\|input.glb> <outputDir> <baseName> [unitScale]`	The alpha.1 converter: glTF 2.0 to a `.cnj` Model/AnimationClip with sidecars. A second form, `--dump-oracle <input> <emptyOutputDir>`, decodes extension-backed positions independently for the project’s own verification.

build/cna_tool_source_to_cnb hero.png build/content/hero.cnb --mipmaps --mip-color-space srgb
build/cna_tool_cnb_info build/content/hero.cnb --chunks
build/cna_tool_gltf_to_cnb models/house.glb build/content house --unit-scale 1.0

See CNB Format for what these files contain and Tutorial 111 for the .cnj route.

The XNB interoperability fixtures

cna_tool_xnb_interop_fixtures <output-directory> [<lzx-output-directory>] writes the CNA-generated XNB corpus (Windows platform, XNA 4.0 container, Reach profile, uncompressed) and each fixture’s expected-value manifest; with a second directory it writes the same fixtures again LZX-compressed. It is a tool rather than a test helper because the corpus is committed to the repository so that an XNA-capable Windows machine, which CNA’s CI does not have, can be pointed at it directly; a test regenerates it to prove the committed bytes have not drifted.

`cna-inspector`

The bridge between a running application’s Inspector agent and a browser. It needs -DCNA_BUILD_INSPECTOR=ON and a game that has called Agent::Start(). Its options are --agent-port (required), --agent-host, --token, --token-file, --http-port, --allow-remote-agent and --help; the token can also come from CNA_INSPECTOR_TOKEN. Everything, including the security notes, is on the Inspector page.

Inspection utilities and harnesses

A few small standalone executables from cmake/Harnesses.cmake are useful for debugging content; none needs a window and none is a shipped product:

Executable	Built when	What it does
`cna_xnb_audio_metadata_dump`	`CNA_BUILD_TESTS`	Loads a `.xnb` SoundEffect through the production `ContentManager` path and prints its metadata (name, decoded duration) as one line of JSON, without playing it.
`cna_xwb_inspect`	`CNA_BUILD_TESTS`	Parses an XACT `.xwb` wave bank and prints every entry’s metadata as JSON, optionally exporting each entry’s audio as a playable `.wav`.
`cna_reference_dump`	`CNA_BUILD_EXAMPLES`, not Emscripten or Android	Dumps enums, state presets, PackedVector and Viewport reference values as JSON for the manual comparison against the FNA reference harness (`scripts/compare-fna-reference.py`).
`cna_strict_xna_api_check`	`CNA_BUILD_TESTS`, GCC or Clang	A compile check, not a tool: it fails to build if the strict-XNA file calls a `CNAEXT`-tagged `Microsoft::Devices` or `Sensors` member.

Benchmarks and developer gates

Two more executables appear only with -DCNA_BUILD_BENCHMARKS=ON: cna_diagnostics_benchmark (see Diagnostics) and cna_inspector_benchmark together with cna_inspector_compiled_out_benchmark. Beyond executables, the repository carries scripts that gate changes; they are aimed at CNA contributors rather than at game authors:

Where	What it checks or produces
`tools/c-api/*.py`	The C route generator (`generate_routes.py`, which writes each family’s C definitions from `modules/c-api/spec/*.toml`) and the C ABI gates: recorded ABI baseline, declared-versus-exported symbols, coverage inventory, compatibility matrix, limitations report, release gate, route-test ratchet, WebAssembly export list, static archive and artifact manifest. See Experimental C API.
`tools/provenance/provenance_gate.py`	That no proprietary binary or font is tracked, that every C++ source under `modules/`, `tools/` and `spikes/` declares `SPDX-License-Identifier: MS-PL`, and that vendored and adapted third-party code is declared.
`scripts/check_.py`, `scripts/check_.sh`	Renderer-identity, combination and target-discipline registries, CNAEXT rules, test display isolation, renderer configure sweeps and similar gates that run in CI.
`tools/link_audit/`, `scripts/check_link_footprint.py`	Why a symbol or module is linked into an executable (`why_linked.py`, `link_closure.py`) and the link-footprint gates. See Link Boundaries & Size.
`tools/audit_xna_runtime_surface.py`	The census that compares CNA’s public surface with Microsoft’s XNA 4.0 documentation and metadata (representation only, not behavior).
`tools/xna-oracle/`, `tools/xna-pipeline-oracle/`	The real-XNA reference scenes and the pipeline oracle used by the verification campaign. See Verification.
`tools/tests/run_gtest_bounded.sh`	A bounded-memory GoogleTest runner.

Deep dives on this topic

Long-form pages that explain the exact semantics, invariants and evidence behind this subject.

Tests, examples, presets and tools: what each verdict proves — What a green result from CNA's test corpus, examples, golden images, CMake presets and developer tools actually establishes, sorted by authority class, and how to read a result before citing it.
The CNJ model toolchain: gltf_to_cnj, the Model envelope and sidecars — What cna_tool_gltf_to_cnj writes, the per-type version-2 Model envelope, which descriptor and sidecar rules the .cnj reader enforces or trusts, route parity and the dual-texture occlusion remap.