Skip to content

feat(linux): improve Wayland support and AppImage integration - #1309

Draft
minpeter wants to merge 2 commits into
pot-app:masterfrom
minpeter:fix/linux-wayland-appimage
Draft

feat(linux): improve Wayland support and AppImage integration#1309
minpeter wants to merge 2 commits into
pot-app:masterfrom
minpeter:fix/linux-wayland-appimage

Conversation

@minpeter

@minpeter minpeter commented Aug 9, 2026

Copy link
Copy Markdown

Why

Pot's current Linux AppImage works on X11, but a clean install on a modern GNOME Wayland session exposes several related problems:

  • the AppImage bundles the build host's libwayland-client.so.0; on newer hosts this can conflict with the compositor/WebKitGTK stack and abort startup with an EGL allocation error;
  • Tauri 1's global shortcut backend does not register shortcuts natively on Wayland, so users must manually configure a desktop shortcut that calls Pot's local HTTP endpoint;
  • the current selection crate falls back by mutating process-wide XDG_SESSION_TYPE and GDK_BACKEND, which can affect the rest of the running UI;
  • the AppImage has no small user-local integration path for installing its command, icon, launcher, and actions;
  • media support depends on host GStreamer plugins that are not consistently present.

This PR makes the AppImage usable as a self-contained Wayland-oriented installation while preserving the existing X11, Windows, and macOS paths.

What changed

AppImage runtime and packaging

  • Remove the bundled libwayland-client.so.0 from the completed AppDir and rebuild only through linuxdeploy's AppImage output plugin. Calling the full linuxdeploy pipeline again would rescan the AppDir and copy the incompatible host library back.
  • Recreate and sign the Tauri updater archive from the corrected AppImage, so the downloadable and updater artifacts contain the same payload.
  • Enable GStreamer bundling for the x86_64 AppImage and install the base/good/libav plugins in the Linux build image.
  • Pin the Linux builder to Rust 1.82. The moving rust:bullseye tag now selects a compiler that fails in this Tauri 1/Wry dependency graph; the pinned image makes releases reproducible and was used for the full Rust verification below.

Native Wayland shortcuts

  • Use org.freedesktop.portal.GlobalShortcuts through ashpd when running in a Wayland session.
  • Convert Pot/Tauri shortcut strings to the XDG shortcut syntax (for example, Ctrl+' becomes CTRL+apostrophe).
  • Keep the existing Tauri global shortcut manager unchanged on X11 and other platforms.
  • Add command-line actions such as pot --selection-translate. They are forwarded through the existing single-instance plugin, providing a compositor/system-shortcut fallback without depending on curl or a fixed HTTP port.

The portal remains responsible for user consent, so the desktop can display its normal shortcut confirmation dialog.

Selected text handling

  • On Linux, try the Wayland primary-selection protocol first and then the X11 primary selection when DISPLAY is available.
  • Do not rewrite process-wide session/backend environment variables during fallback.
  • Keep the existing selection crate implementation for Windows and macOS.

This intentionally does not claim universal selected-text access on Wayland. If a compositor does not expose the primary-selection protocol, native Wayland clients cannot provide their selection through this mechanism; the documentation recommends copying the text or using clipboard monitoring in that case.

User-local AppImage integration

  • Add packaging/linux/install-appimage.sh to install or uninstall the AppImage for the current user.
  • Install a stable pot command, desktop entry, icon, and desktop actions for translation/OCR.
  • Publish the script beside AppImage artifacts and document the Wayland behavior in the Chinese, English, and Korean READMEs.

No onboarding/default translation-provider configuration is changed by this PR.

Verification

  • Repacked the Pot 3.0.7 x86_64 AppImage and verified that libwayland-client.so.0 is absent from the final image.
  • Ran the corrected AppImage in an isolated GNOME Wayland session for 10 seconds without the previous EGL/Wayland startup error.
  • pnpm build
  • cargo +1.82.0 test --manifest-path src-tauri/Cargo.toml in Debian Bullseye with WebKitGTK 4.0: 3 tests passed.
  • cargo fmt --check and targeted Prettier check.
  • bash -n for the modified packaging scripts.
  • Installed and uninstalled the real 3.0.7 AppImage in an isolated temporary HOME; verified the executable, symlink, icon, desktop entry, and all four desktop actions.

Review notes

The two commits are separated by concern: the first contains the AppImage Wayland ABI fix, and the second contains the portal, selection, integration, and build-reproducibility improvements. The PR is opened as a draft so the Linux packaging/portal approach can be discussed before merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant