docs(building): clarify from-source DP registration (ABI-stale plug-in case)#642
Open
leaiss wants to merge 2 commits into
Open
docs(building): clarify from-source DP registration (ABI-stale plug-in case)#642leaiss wants to merge 2 commits into
leaiss wants to merge 2 commits into
Conversation
…n case) The "from-source needs a registered display processor" callout only described a machine with nothing registered. The same XRT_ERROR_DEVICE_ CREATION_FAILED / "Failed to initialize OpenXR" failure also happens when a plug-in *is* registered but is ABI-stale — e.g. an older installer's sim-display/leia-sr that a from-source runtime built ahead of that release rejects at negotiate (`negotiate returned -17`, "no registered plug-in claimed the system"). Add a second paragraph covering that case, note that "registered" does not imply "ABI-matched", and point at `displayxr-cli selftest` as the headless diagnostic. Also reword the lead from the informal "The step everyone misses" to "Windows requires an explicit plug-in registration step". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The callout already names `displayxr-cli selftest` as the headless diagnostic; also point at the per-process runtime log (`%LOCALAPPDATA%\DisplayXR\DisplayXR_<exe>.<pid>_<ts>.log`), where the authoritative cause (`negotiate returned …`, which plug-in was rejected) is printed — that's where a dev hitting "Failed to initialize OpenXR" first looks. The log path is otherwise only mentioned far down in the dev-iteration / VS-debug sections. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Extends the "from-source build needs a registered display processor" callout in
docs/getting-started/building.mdto cover the case that actually trips people up: a plug-in is registered, but it's ABI-stale.Why
The existing callout only described a machine with nothing registered ("building from source does not register it → no display processor"). But the identical
XRT_ERROR_DEVICE_CREATION_FAILED/ "Failed to initialize OpenXR" failure also occurs when a plug-in is registered from a prior installer (e.g.sim-display/leia-srfrom a released bundle) and a from-source runtime built ahead of that release ABI-rejects it at negotiate.This came up debugging a colleague's from-source build:
displayxr-cli selftestshowedA new
mainruntime (ABI v4) rejecting the older installer-registered plug-ins. "I have DisplayXR installed and plug-ins registered" was true, yet init still failed — the existing doc gave no hint that an existing registration can be stale, nor a diagnostic.Changes
displayxr-cli selftestas the headless diagnostic.Docs-only —
DetectChangesshort-circuits the build jobs.🤖 Generated with Claude Code