Skip to content

Building from Source

Build Yap v0.5.0 with Go 1.23, Node 20, pinned Wails, and platform dependencies; distinguish dev builds from release packages.

This guide was checked against v0.5.0. For exact release packaging, use the v0.5.0 workflow. For the published app, use installation.

Toolchain

ToolReviewed source
Gogo.mod requires 1.23; release workflow uses 1.23
Node.jsRelease workflow uses 20
Wails CLIMatch go.mod: v2.10.1 at this commit
whisper.cppRelease workflow pins v1.9.5
Native toolsC compiler, pkg-config, and platform UI/audio libraries
git clone --branch v0.5.0 https://github.com/ApplauseLab/yap.git
cd yap
go mod download
go install github.com/wailsapp/wails/v2/cmd/wails@v2.10.1
npm --prefix frontend ci
wails doctor

If building a later commit, derive the Wails version from its go.mod, as release CI does. Do not silently substitute @latest for a pinned toolchain.

macOS

Install Xcode Command Line Tools and native dependencies:

xcode-select --install
brew install portaudio pkg-config

For an unbundled development build, provide compatible whisper-server and whisper-cli binaries (for example via Homebrew), or follow the pinned release scripts. Current release packaging uses scripts/ci/build-whisper-macos.sh and scripts/ci/bundle-macos-runtime.sh to build, audit, sign, and test the bundled runtime. It is more than a bare wails build.

wails dev
wails build -platform darwin/arm64 -o Yap

The shipping workflow builds Apple Silicon. An Intel build needs matching x86_64 libraries and a separately verified runtime; changing to darwin/universal alone does not make all bundled dependencies universal.

Windows

Use Go, Node, a Wails-compatible CGO C compiler, and WebView2. PortAudio is not supplied by Go bindings alone. The release workflow installs portaudio:x64-windows through pinned vcpkg, sets CGO include/library paths, builds the Whisper executables, and copies their DLL dependencies.

$env:CGO_ENABLED = "1"
wails doctor
wails dev
wails build -platform windows/amd64 -o Yap.exe

Install NSIS and use -nsis for an installer. Follow the release workflow for the actual native dependency setup and portable layout. Keep portaudio.dll beside Yap.exe, and Whisper executables plus required runtime DLLs in bin. The bundled local inference runtime targets AVX2-capable x64 CPUs.

Linux

On Ubuntu 22.04:

sudo apt update
sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.0-dev portaudio19-dev libx11-dev xclip xdotool
wails dev
wails build -platform linux/amd64 -o yap

On Ubuntu 24.04, install libwebkit2gtk-4.1-dev instead of 4.0 and build with:

wails build -platform linux/amd64 -o yap -tags webkit2_41

Use the corresponding tag in development too. Global hotkeys use X11; Wayland-native support is not implemented. Release packaging additionally needs CMake, patchelf, and AppImage tooling, and bundles the Whisper executables and libraries. A bare executable is not a complete AppImage or .deb.

Isolate development data

Yap v0.5.0 supports YAP_CONFIG_DIR, which separates your development config, models, logs, and recordings from the installed app:

YAP_CONFIG_DIR="$HOME/.yap-dev" wails dev

PowerShell equivalent:

$env:YAP_CONFIG_DIR = Join-Path $HOME ".yap-dev"
wails dev

YAP_MODEL_BASE_URL points development model downloads at a test mirror. These overrides are not present in 0.4.2. WHISPER_CPP_PATH is not a supported environment variable in the reviewed implementation.

Test

go test ./...
npm --prefix frontend test
npm --prefix frontend run build

Native tests need the OS-specific toolchain. Some runtime/audio tests are opt-in and require model/audio fixtures or native permissions; consult the test source and CI workflow rather than interpreting skipped tests as platform verification. scripts/windows-startup-smoke.ps1 exercises Windows startup; release CI also verifies runtime inference and packaging.

See project structure and contributing for the change workflow.