CNA-BUG-221: RunContentCompiler documentation says XNB output writers are registered only for --format xnb; they are registered on every run

CNA snapshot 009d40f5  ·  Known Issues › Current bugs  ·  source links pinned to 009d40f5

ContentCompiler.hpp ties the coordinator's XNB writer registration to '--format xnb', but tools/content/content.cpp registers them unconditionally before freezing the registry.

Identifier

CNA-BUG-221

Category

Bug

Subsystem

Documentation & release tooling

Status

Open

Verified against

CNA 009d40f5 (009d40f5dd085c4e674d3479675fac84b12b3e0a)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

CNA::Content::Pipeline::RunContentCompiler (both overloads: pre-built registry and registry factory)

Expected behaviour

The embedding API documents what the coordinator does to a caller's registry: on every invocation it registers the XNB output writers bound to the parsed container options, because a project file may select xnb per asset, and writer resolution is keyed by (format, processed type) so they never shadow the CNB writers.

Actual behaviour at TARGET

ContentCompiler.hpp says the registry stays mutable "for exactly one reason: when the command line selects --format xnb the coordinator registers the XNB output writers". tools/content/content.cpp calls RegisterXnbOutputContentPipeline "whatever --format says", for both overloads, and then freezes the registry. The neighbouring RegisterBuiltInContentPipeline comment ("RunContentCompiler() adds them once it has parsed them") is accurate.

Consequence by reading: an embedder who, following the header, registers the XNB writers itself for a build without --format xnb gets ContentPipelineRegistry::RegisterWriter's "writer 'CNA.XnbTexture2DWriter' is already registered" and exit code 2 on every run.

Source locations

• modules/content/include/CNA/Content/Pipeline/ContentCompiler.hpp — RunContentCompiler(arguments, registry) doc comment
• tools/content/content.cpp — Run - unconditional RegisterXnbOutputContentPipeline before Freeze
• modules/content/src/Pipeline/ContentPipeline.cpp — ContentPipelineRegistry::RegisterWriter - duplicate names throw

Evidence

Checked by reading at 009d40f5; not executed. The collision consequence follows from RegisterWriter's duplicate-name check and was not run. Recorded first on the site's content-pipeline internals page as a stale header comment.

Focused reproduction

Illustrative; not compiled.

using namespace CNA::Content::Pipeline;
auto registry = std::make_shared<ContentPipelineRegistry>();
RegisterBuiltInContentPipeline(*registry);
RegisterXnbOutputContentPipeline(*registry, {});  // the header implies this is needed without --format xnb
int rc = RunContentCompiler(arguments, registry);  // arguments do not select --format xnb
// rc == 2: "writer 'CNA.XnbTexture2DWriter' is already registered."

Current tests

The pipeline tests under modules/content/tests/CNA/Content/Pipeline exercise the coordinator but no test checks documentation.

Regression test

None needed for the comment itself; an embedding test that passes a registry already holding the XNB writers would pin whichever behaviour the corrected documentation promises.

Blast radius

Only C++ embedders of RunContentCompiler who read the header; cna-content itself is unaffected.

Workaround

Do not register the XNB output writers yourself; the coordinator always does.