danvics/Handy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: clarify Linux gtk-layer-shell runtime requirements (#748)

Browse source
This commit is contained in:
Martin Kleine 2026-02-09 09:12:00 +01:00 committed by GitHub
parent a9024d07bc
commit 306bcb0d52
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 13 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
BUILD.md
View file

@ -32,12 +32,13 @@ This guide covers how to set up the development environment and build Handy from
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install build-essential libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf cmake
sudo apt install build-essential libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev patchelf cmake
# Fedora/RHEL
sudo dnf groupinstall "Development Tools"
sudo dnf install alsa-lib-devel pkgconf openssl-devel vulkan-devel \
gtk3-devel webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel \
gtk-layer-shell gtk-layer-shell-devel \
cmake
# Arch Linux

11
README.md
View file

@ -105,6 +105,17 @@ Without these tools, Handy falls back to enigo which may have limited compatibil
**Other Notes:**
- **Runtime library dependency (`libgtk-layer-shell.so.0`)**:
- Handy links `gtk-layer-shell` on Linux. If startup fails with `error while loading shared libraries: libgtk-layer-shell.so.0`, install the runtime package for your distro:
| Distro | Package to install | Example command |
| ------------- | -------------------------- | -------------------------------------------- |
| Ubuntu/Debian | `libgtk-layer-shell0` | `sudo apt install libgtk-layer-shell0` |
| Fedora/RHEL | `gtk-layer-shell` | `sudo dnf install gtk-layer-shell` |
| Arch Linux | `gtk-layer-shell` | `sudo pacman -S gtk-layer-shell` |
- For building from source on Ubuntu/Debian, you may also need `libgtk-layer-shell-dev`.
- The recording overlay is disabled by default on Linux (`Overlay Position: None`) because certain compositors treat it as the active window. When the overlay is visible it can steal focus, which prevents Handy from pasting back into the application that triggered transcription. If you enable the overlay anyway, be aware that clipboard-based pasting might fail or end up in the wrong window.
- If you are having trouble with the app, running with the environment variable `WEBKIT_DISABLE_DMABUF_RENDERER=1` may help
- You can manage global shortcuts outside of Handy and still control the app via signals. Sending `SIGUSR2` to the Handy process toggles recording on/off, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings. Example (Sway):