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

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

Browse source 
Document the deb extraction method for installing from source on Linux,
and the AppImage build failure on rolling-release distros (Arch, CachyOS,
etc.) caused by linuxdeploy's bundled strip being too old.

Closes #946

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Ari 2026-03-04 07:14:23 -05:00 committed by GitHub
parent a6b5c32cdb
commit a50c59ce90
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 61 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
BUILD.md
View file

@ -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.