Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

docs: add Linux install steps and AppImage troubleshooting to BUILD.md (#951)

Aria50c59ce909c
diff --git a/BUILD.md b/BUILD.md
index 235417a7..78b1365b 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -67,3 +67,64 @@ bun install
```bash
bun tauri dev
```
+
+### 4. Build for Production
+
+```bash
+bun run tauri build
+```
+
+This compiles a release binary and generates platform-specific bundles (deb, rpm, AppImage on Linux; dmg on macOS; msi on Windows).
+
+## Linux Install (from source)
+
+The raw binary (`src-tauri/target/release/handy`) cannot run standalone — it needs Tauri resource files (tray icons, sounds, VAD model) to be co-located at the expected path.
+
+**Install from the deb bundle** (works on any Linux distro):
+
+```bash
+cd /tmp
+ar x /path/to/Handy/src-tauri/target/release/bundle/deb/Handy_*_amd64.deb data.tar.gz
+tar xzf data.tar.gz
+sudo cp usr/bin/handy /usr/bin/
+sudo cp -r usr/lib/Handy /usr/lib/
+sudo cp -r usr/share/icons/hicolor/* /usr/share/icons/hicolor/
+sudo cp usr/share/applications/Handy.desktop /usr/share/applications/
+```
+
+After subsequent rebuilds, only the binary needs re-copying:
+
+```bash
+sudo cp src-tauri/target/release/handy /usr/bin/
+```
+
+Resources only need re-copying if they change upstream (new icons, sounds, etc.).
+
+## Troubleshooting
+
+### AppImage build fails on Arch / rolling-release distros
+
+`linuxdeploy` bundles its own `strip` binary which is too old to process system libraries built with newer toolchains on rolling-release distros (Arch, CachyOS, Manjaro, EndeavourOS).
+
+The error from Tauri:
+
+```
+Bundling Handy_*_amd64.AppImage
+failed to bundle project `failed to run linuxdeploy`
+```
+
+Tauri swallows the real linuxdeploy error. To see it, run linuxdeploy manually:
+
+```bash
+cd src-tauri/target/release/bundle/appimage
+~/.cache/tauri/linuxdeploy-x86_64.AppImage --appimage-extract-and-run \
+ --appdir Handy.AppDir --plugin gtk --output appimage
+```
+
+**Workaround:** The binary, deb, and rpm bundles all build fine — only the AppImage step fails. To skip it:
+
+```bash
+bun run tauri build -- --bundles deb
+```
+
+Then install using the deb extraction method above.