Linux Release Requirements

Linux releases need the same core workflows, support ownership, and regression coverage as Windows releases. Track platform differences explicitly. Keep untested targets marked as unverified.

Required support matrix

For each release, record:

• Product and plugin versions, source revisions, artifact names, and checksums.
• Distribution and version, architecture, kernel, desktop/version, and X11 or Wayland.
• Package format, installation method, GPU/driver, audio service, and connected hardware.
• Native Steam or Flatpak Steam, Proton version where used, and Desktop or Gaming Mode.
• Test date, owner, result, evidence location, and unresolved issues.

Use Passed, Failed, Not tested, or Not applicable for each cell. Explain every exclusion. Do not inherit a pass across architectures, package formats, desktops, or products.

The current alpha targets x64 PCs and Steam Deck on Bazzite, SteamOS Desktop Mode, and Ubuntu Desktop. Full desktop and device testing is in progress. Record exact OS versions and results before claiming compatibility.

Broader coverage includes other distributions, arm64, X11 and Wayland combinations, Steam Gaming Mode, and dedicated full screen login sessions. Track these separately from the current alpha scope. Build targets and automated contracts do not establish desktop or device acceptance.

Packaging and dependencies

• Build Linux desktop artifacts in Linux CI, a Linux VM, or a suitable Linux build environment.
• Publish architecture-matched native SQLite, SDL, XML, graphics, media, and .NET dependencies used by each product.
• Declare the minimum glibc and runtime baseline. Test against the oldest supported distribution.
• Load native modules under the packaged Electron runtime. A JavaScript build alone does not pass this gate.
• Validate AppImage and FUSE-free startup independently. Test each published deb, rpm, archive, and installer.
• Keep setup usable without root for user-space packages and immutable systems.
• Verify checksums, executable modes, desktop entries, icons, application identity, URL handlers, and paths containing spaces or non-ASCII characters.
• Define update ownership for each package format. Test interrupted download, failed extraction, retry, upgrade, and recovery without losing user data.
• Test uninstall with data retention and explicit data removal separately.
• Publish known limits, dependencies, and recovery steps beside the release download.

HyperHQ and HyperSpin provide npm run dist:linux source build commands. Their package gates exercise Linux native dependencies. Those gates do not replace desktop acceptance.

Plugins and templates

Declare Linux in supported platform metadata only after the Linux artifact passes installation and runtime tests. Use executableProviders for the correct entry point:

{
  "executableProviders": {
    "windows": "MyPlugin.exe",
    "linux": "MyPlugin"
  }
}

This is a manifest fragment. Keep the required identity, version, protocol, and capability fields described in the developer guide.

• Publish each supported CPU architecture. Document any runtime dependency.
• Compile Go binaries for the target. Publish .NET for the matching Linux runtime identifier. Build frozen Python executables on Linux.
• Test starter build and install instructions on Linux. Replace Windows copy commands and .exe paths in Linux examples.
• Preserve executable permission through archive extraction or installer repair.
• Use exact case for manifest paths, assets, libraries, and entry points.
• Pass executable arguments as separate values. Avoid shell interpolation of game paths or user input.
• Keep protocol output separate from diagnostics. Test authentication, reconnect, shutdown, timeout, and process cleanup.
• Validate native dependencies and device access in the installed plugin, including sandboxed launch paths.
• Hide unavailable Windows actions or return a clear unsupported result before changing system state.
• Test Essentials helpers and the parent app together. Verify capability differences such as Linux guardian mute rejection.

Desktop acceptance

Area	Required result
Fresh setup	Install, sign in, configure paths, install core plugins, and open every companion app
Library	Import nested folders, collections, tags, profiles, media, and metadata; restart with saved state intact
Game launch	Run native and configured Proton games; track the actual game process through wrappers
Lifecycle	Pause, resume, mute where supported, restart, exit, crash recovery, and return of input focus
Input	Keyboard, controller-only navigation, Bluetooth reconnect, multiple players, and configured cabinet devices
Display	Fullscreen, mixed scaling, portrait/marquee layout, display reconnect, and compositor identity
Media	Theme rendering, video/audio, manuals, missing assets, codec failures, and thumbnail generation
Data	Backup/restore, Windows-to-Linux paths, external mounts, low disk space, and relocation
Login and power	Delayed desktop startup, Gaming Mode launch, suspend/resume, and shutdown cleanup
Maintenance	Plugin install/repair/update, application update, retained data, and uninstall
Accessibility	Keyboard focus, readable scaling, clear unsupported actions, and no required mouse for cabinet navigation
Performance	Startup time, idle CPU, memory, navigation latency, frame pacing, and pause latency on recorded hardware

Record measured results and agreed regression limits. Performance changes must preserve behavior. A headless test or Windows fixture with Linux paths does not establish physical Linux input, display, or GPU acceptance.

Web apps and services

HyperTheme needs Linux browser coverage for editing and publishing, plus packaged HyperSpin playback. Test account redirects, clipboard, file selection, downloads, fonts, WebGL, audio, and recovery from expired sessions.

HyperAuth, HyperAI API, HyperList, ratings providers, and media services need the same client contracts on Linux. Test live sign-in, catalog access, entitlement checks, imports, media downloads, retry, and offline recovery. Contract fixtures do not establish live provider acceptance.

For Linux service hosting, document process supervision, environment configuration, secret provisioning, TLS/proxy handling, persistent storage, file ownership, backups, logs, health checks, upgrades, and rollback. IIS deployment instructions apply to Windows hosting. Desktop support does not require moving existing services to Linux.

HyperCapture acceptance requires the target Linux server, Chromium, FFmpeg, synchronized page audio, GPU passthrough where used, an actual NVENC encode, and CPU fallback. Complete the queued flow through upload and HyperTheme attachment. Local CPU recording does not establish GPU-server or live upload acceptance.

Release decision

The product owner reviews failed and untested cells before publishing the support statement. Core setup, library, launch, controls, data protection, and recovery failures block a first-class support claim for the affected target.

Document external Windows-only integrations by name. Provide a tested Linux alternative where available. Do not represent Wine compatibility or an untested replacement as native feature parity.

Attach the completed matrix and evidence to the release. Keep customer setup pages aligned with the accepted package versions and documented limits.