displayxr-installer
End-user meta-installer for DisplayXR — a single .exe / .pkg bundle that chains the OpenXR runtime, Shell, Leia SR plug-in, MCP Tools, and the open-model conversion provider into one guided install.
Tracks issue DisplayXR/displayxr-runtime#284.
Download
One-time install warning (unsigned)
Version 1 of the bundle ships unsigned. SmartScreen / Gatekeeper show a one-time prompt on the bundle itself, then everything inside installs silently.
- macOS: right-click the downloaded
.pkg → Open → click Open in the dialog. Apple requires this for unsigned installers — notarization is tracked in DisplayXR/displayxr-runtime#280.
- Windows: if SmartScreen shows "Windows protected your PC", click More info → Run anyway. Authenticode signing is tracked in
DisplayXR/displayxr-runtime#281.
What gets installed
| Component | macOS | Windows | Linux |
|---|
| DisplayXR Runtime | ✅ | ✅ | ✅ |
| DisplayXR Shell | — (Windows-only today) | ✅ | — |
| Leia SR Plug-in | — (Windows-only, vendor SDK) | ✅ | ✅ |
| MCP Tools | — (Windows-only today) | ✅ | — |
| Open Conversion provider (open-model 2D→3D) | — (no macOS build today) | ✅ | ⏳ ships a per-user tarball, not a .deb |
| Demos (gauss, model viewer, media player, avatar, earthview) | ✅ | ✅ | ⏳ join when they ship a Linux .deb |
macOS users get a runtime-only install today; additional components join the bundle as they publish .pkg artifacts.
The exact version pins for each release live in versions.json at the tagged commit.
Linux bundle
The Linux bundle is a .tar.gz containing the component .debs + an install.sh:
tar -xzf DisplayXRBundle-*-linux-amd64.tar.gz
cd DisplayXRBundle-*-linux-amd64
sudo ./install.sh # sudo ./uninstall.sh to remove
To verify a download first, grab SHA256SUMS from the same release page into the same folder and run:
sha256sum -c SHA256SUMS --ignore-missing # checks only the assets you downloaded
SHA256SUMS covers every bundle asset (.exe, .pkg, .tar.gz, .apk); the .exe line matches the signed installer.
It installs the DisplayXR runtime + Leia SR display-processor plug-in with zero environment variables — the runtime registers the OpenXR ActiveRuntime and searches /usr/lib/displayxr/plugins by default. Without the Leia SR runtime (the commercial leiasr-runtime package, shipped separately by Leia — not in this bundle) apps run on the built-in sim-display fallback; install it and the Leia display processor claims the display automatically. install.sh detects it and guides you.
Demos are not included on Linux yet — they ship Windows .exe / macOS .pkg today but no Linux .deb. build-bundle-linux.sh already loops over them and will pull each one in automatically once its repo publishes a *_amd64.deb release asset (and components.sh gains its DEB_LINUX glob). Tracks DisplayXR/displayxr-runtime#781.
Android installer APK
Android has no NSIS equivalent — an App Bundle or a set of split APKs describes exactly one app —
so the "one tappable artifact" job is done by an app. DisplayXR-Installer-<ver>.apk reads the same
versions.json pin matrix, downloads each pinned component from its GitHub release, installs them
in dependency order — on a 3D tablet, starting with the pinned vendor display services, which it
downloads from updates.displayxr.org and verifies against the vendor certificate it carries (on the
factory services DisplayXR runs but 3D does not work) — and then performs the post-install steps that
installing APKs does not do:
opening the runtime once (without which every OpenXR app dies at instance creation with
XR_ERROR_RUNTIME_UNAVAILABLE), and deep-linking to the runtime's "Display over other apps" switch
(without which see-through apps render on black while 3D keeps working).
The browser is opt-in, mirroring the desktop --with browser rule, and is refused unless the
runtime actually on the tablet is the pinned one — the mismatched pair renders all 3D content in the
browser black with no error on screen.
It is not silent: Android confirms each package separately unless the installer is a device owner
or a privileged system app. Full scope, the steps it cannot automate, and the failure states:
android-installer/README.md. Tracks
#62.
Developer install
Building DisplayXR from source or running a dev box? Use the runtime repo's orchestrator instead:
# macOS / Linux
git clone https://github.com/DisplayXR/displayxr-runtime
cd displayxr-runtime
./scripts/setup-displayxr.sh
:: Windows (elevated)
git clone https://github.com/DisplayXR/displayxr-runtime
cd displayxr-runtime
scripts\setup-displayxr.bat
The end-user bundle in this repo is a thin wrapper that chains the same per-component installers via NSIS / productbuild.
Building the bundle locally
# macOS
./scripts/build-bundle.sh --version v0.1.0-rc1
# → _out/DisplayXRBundle-0.1.0-rc1.pkg
# Windows
scripts\build-bundle.bat --version v0.1.0-rc1
:: → _out\DisplayXRBundle-0.1.0-rc1.exe
Both scripts read versions.json, fetch the per-component asset table from the runtime repo at the pinned runtime tag, download each component's installer from its GitHub Release, and assemble the bundle.
Release flow
Releases are cut by manual workflow_dispatch on .github/workflows/publish-bundle.yml:
- Bump
versions.json in a PR (pinning each component to a specific tag).
- Merge.
- Run Publish bundle → enter the bundle tag (e.g.
v0.1.0) → workflow builds both platforms in parallel and attaches .exe + .pkg to a new GitHub Release.
Not auto-triggered on component releases — that would be brittle (e.g., a runtime patch release shouldn't republish a bundle that wasn't compat-tested against the latest Shell).
License
Apache-2.0.
