Skip to content

BUILD.md

Latest commit

 

History

History
130 lines (89 loc) · 3.38 KB

BUILD.md

File metadata and controls

130 lines (89 loc) · 3.38 KB

Build Instructions

This guide covers how to set up the development environment and build Handy from source across different platforms.

Prerequisites

All Platforms

Platform-Specific Requirements

macOS

  • Xcode Command Line Tools
  • Install with: xcode-select --install

Windows

  • Microsoft C++ Build Tools
  • Visual Studio 2019/2022 with C++ development tools
  • Or Visual Studio Build Tools 2019/2022

Linux

  • Build essentials

  • ALSA development libraries

  • Install with:

    # 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 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
sudo pacman -S base-devel alsa-lib pkgconf openssl vulkan-devel \
  gtk3 webkit2gtk-4.1 libappindicator-gtk3 librsvg gtk-layer-shell \
  cmake

Setup Instructions

1. Clone the Repository

git clone git@github.com:cjpais/Handy.git
cd Handy

2. Install Dependencies

bun install

3. Start Dev Server

bun tauri dev

4. Build for Production

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):

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:

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:

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:

bun run tauri build -- --bundles deb

Then install using the deb extraction method above.