fix(desktop): SKIKO_RENDER_API env escape hatch for Linux hybrid-GPU SEGV (#546)

[rainxchzed]

Addresses #546 — Linux AppImage / pkg.tar.zst SEGVs as normal user on Bazzite DX with hybrid GPU (Radeon 780M iGPU + RTX 4060 dGPU). Works under `sudo` only.

Diagnosis

The crash is in native code (Skiko / Skia), before any Java exception handler runs — that's why the reporter sees a bare `segmentation fault (core dumped)` with no log output and `CrashReporter` (which IS installed first) doesn't capture anything. The pattern is consistent with the Nvidia proprietary driver path on hybrid-GPU setups: when the unprivileged process tries to bring up an OpenGL/Vulkan context against the dGPU, the proprietary stack SEGVs the JVM. Sudo dodges it because root has different DRM render-node access.

We can't catch this in Java. We CAN give the reporter (and any future hybrid-GPU sufferers) a working escape hatch they can set without rebuilding the app.

Fix

Honour `SKIKO_RENDER_API` from the process environment on Linux only. If set, copy into the `skiko.renderApi` system property before any Compose / Skiko code runs. If unset, leave Skiko to its default — pinning a specific backend unconditionally would regress the much larger population that does have a working accelerated path.

Mac / Windows skipped — different graphics stacks, different bug class.

This means a stuck reporter can launch via:

```bash
SKIKO_RENDER_API=SOFTWARE ./GitHub-Store-x86_64.AppImage # CPU rendering

or

SKIKO_RENDER_API=OPENGL ./GitHub-Store-x86_64.AppImage # force OpenGL
```

`SOFTWARE` is the safe bet for Bazzite DX hybrid setups — slow but always works. `OPENGL` is the fallback if Vulkan was the actual culprit.

Other workarounds for the user (documented in issue reply)

• `__NV_PRIME_RENDER_OFFLOAD=0` to force iGPU (AMD) — reporter says AMD path works.
• Membership in `render` and `video` groups: `sudo usermod -aG render,video $USER`.
• For Bazzite DX specifically: `ujust setup-nvidia` or rebase off the dGPU-image variant.

Test plan

• `:composeApp:compileKotlinJvm` ✅
• Local CodeRabbit: 0 findings.
• Cannot reproduce locally without a Bazzite/Nvidia hybrid setup. Reporter on the issue can verify `SKIKO_RENDER_API=SOFTWARE` in the next 1.9.0 release; if successful, we'll surface the escape hatch in the README.

Out of scope

• Auto-detect hybrid GPU and force `SOFTWARE` — too aggressive, would slow down working setups.
• AppImage launcher script that sets the env var by default — defer until we hear back from the reporter.

Summary by CodeRabbit

• Bug Fixes
  • Enhanced Linux rendering backend initialization to better support systems with hybrid GPU configurations, including support for environment-variable-based configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7dc22364-a1bf-42eb-9053-c56f57ce3957

📥 Commits

Reviewing files that changed from the base of the PR and between c8fcae0 and 754e4fe.

📒 Files selected for processing (1)

• composeApp/src/jvmMain/kotlin/zed/rainxch/githubstore/DesktopApp.kt

---

Walkthrough

The PR adds an environment-based render backend configuration mechanism for Skiko on Linux systems. A new helper function reads the SKIKO_RENDER_API environment variable and applies it to the skiko.renderApi system property when running on Linux and the property is not already configured, providing an escape hatch for hybrid-GPU SEGV scenarios during early application startup.

Changes

Linux Skiko Render Backend Configuration

Layer / File(s)	Summary
Helper Function Implementation composeApp/src/jvmMain/kotlin/zed/rainxch/githubstore/DesktopApp.kt	New private function selectLinuxRenderBackendIfRequested detects Linux, checks whether skiko.renderApi is already set, reads SKIKO_RENDER_API environment variable, and applies it to the system property when present.
Main Method Integration composeApp/src/jvmMain/kotlin/zed/rainxch/githubstore/DesktopApp.kt	The main function calls the new render backend helper immediately after installing A11yCrashGuard, before proceeding with the rest of application initialization.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• OpenHub-Store/GitHub-Store#451: Installs A11yCrashGuard in DesktopApp.kt startup, which this PR extends by adding render backend configuration immediately after.

Poem

🐰 On Linux paths where graphics dance,
Nvidia's quirks demand a chance—
Env vars whisper render's way,
Skiko listens, smooth today!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a SKIKO_RENDER_API environment variable escape hatch to fix a Linux hybrid-GPU segfault issue.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/linux-render-fallback

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}