Command-Line Tools

CNA snapshot 009d40f5 · 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 009d40f5: 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 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/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.