Building Gnomad Webcanvas for macOS, Linux, and Windows

Prerequisites (all platforms)

• Node.js LTS (22 recommended)
• Rust stable (rustup)
• Platform SDKs for the OS you are building on (cross-compiling is possible but not covered here)

cd 05_apps_and_extensions/gnomad-preview
npm install
npm run build

Tauri v2 prerequisites — install WebView2 (Windows), Xcode CLT (macOS), webkit2gtk 4.1 (Linux).

Development

# Web only (browser at http://localhost:5173)
npm run dev

# Desktop (Vite + Tauri shell) — Wayland default on modern Linux
npm run tauri:dev

# Linux fallback if WebKit/GPU issues (forces X11)
npm run tauri:dev:x11

# Unit tests (Vitest)
npm run test
npm run test:watch

Production build

Use platform-specific commands (base tauri.conf.json has no bundle targets):

npm run tauri:build:linux    # .deb, .rpm, AppImage
npm run tauri:build:macos    # .app, .dmg
npm run tauri:build:windows  # NSIS .exe (Windows Alpha)

Output under src-tauri/target/release/bundle/.

Checksums after a local build:

bash scripts/sha256-bundles.sh

macOS

npm run tauri:build

Output: src-tauri/target/release/bundle/macos/Gnomad Webcanvas.app

• Native File menu (Open / Save / Save As / Quit)
• Window title reflects filename and dirty state
• Signing / notarization: optional — configure GitHub secrets in .env.example when ready

Minimum macOS version: 10.15 (set in tauri.conf.json).

Linux

Install dependencies:

# Fedora / Nobara
bash scripts/install-linux-deps.sh

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

On Wayland, use npm run tauri:dev. For WebKit/GPU issues, use npm run tauri:dev:x11.

npm run tauri:build:linux
# or full local prep (deps + npm ci + build):
bash scripts/build-linux-local.sh

On Fedora 43 / Nobara / Arch and other distros with modern glibc, use npm run tauri:build:linux — it sets NO_STRIP=1 and APPIMAGE_EXTRACT_AND_RUN=1 so linuxdeploy can bundle AppImages without failing on .relr.dyn ELF sections.

Plain npm run tauri:build still works for .deb and .rpm; AppImage may fail unless those env vars are set.

Do I need a build per Linux kernel?

No. One x86_64 build covers all common desktop distros (Fedora, Nobara, Ubuntu, Debian, Arch, etc.) regardless of kernel version. Ship three Linux formats and users pick what fits:

You only need separate builds per CPU architecture (e.g. x86_64 vs aarch64/ARM). Kernel updates on the same machine do not require a new installer.

On Wayland/KDE, the desktop launcher must set GDK_BACKEND=x11 and WEBKIT_DISABLE_DMABUF_RENDERER=1 (see src-tauri/bundle/linux/webcanvas.desktop.hbs). Without these, the dock icon may fail with a Wayland protocol error.

Launch on Wayland/KDE if the window is blank:

GDK_BACKEND=x11 WEBKIT_DISABLE_DMABUF_RENDERER=1 gnomad-webcanvas

Or use scripts/launch-linux.sh after installing the RPM.

On Wayland, use npm run tauri:dev. For WebKit/GPU issues, use npm run tauri:dev:x11.

Windows

Build on Windows with WebView2 (silent bootstrapper in tauri.windows.conf.json):

npm run tauri:build:windows
# or on Windows:
powershell -File scripts/build-windows-release.ps1

Output: NSIS .exe installer.

Channel: 0.1.0-alpha.1 — Windows Alpha. Limited QA; feedback welcome via Get page.

Code signing: optional — WINDOWS_CERTIFICATE secrets in CI (see .env.example). Unsigned builds may trigger SmartScreen.

CI: Windows installers publish only on v*-alpha* tags. Linux/macOS beta releases are unaffected.

CI release builds

Tagged pushes (v*) trigger .github/workflows/release.yml:

Releases publish automatically as pre-releases (prerelease: true). Flip to stable in the workflow when ready.

Each matrix job uploads SHA256SUMS-<target>.txt artifacts.

See RELEASE_RUNBOOK.md.

Verification after build

npm run lint
npm run test
npx tsc -b --noEmit
npm run build

Before tagging: walk QA_CHECKLIST.md on at least one platform.

Cross-platform parity

Use CROSS_PLATFORM_CHECKLIST.md when adding OS-facing features.

Built with ❤️ by Gnomad Studio 🦙