docs: add dev-setup.md — authoritative build deps, launch commands, and gotcha reference

2026-04-18 10:34:35 +01:00
parent ac46949b01
commit 82c2631f28
1 changed files with 129 additions and 0 deletions
--- a/docs/dev-setup.md
+++ b/docs/dev-setup.md
@@ -0,0 +1,129 @@
+---
+name: dev-setup
+type: reference
+tags: [setup, dependencies, build, linux, fedora]
+description: Authoritative build dependencies and launch instructions for Kon on Fedora Linux
+---
+
+# Kon — Developer Setup
+
+Last updated: 2026/04/18. Primary dev target: Fedora 43, x86_64, KDE Wayland, NVIDIA RTX 4070.
+
+---
+
+## System dependencies
+
+### Required (CPU build)
+
+```bash
+sudo dnf install cmake clang-devel
+```
+
+| Package | Why |
+|---|---|
+| `cmake` | whisper-rs-sys build system |
+| `clang-devel` | bindgen header generation for whisper-rs-sys |
+
+**Fedora-specific:** `libclang.so` lives in `/usr/lib64/llvm21/lib64/`, not on the standard search path. Set permanently:
+
+```bash
+set -Ux LIBCLANG_PATH /usr/lib64/llvm21/lib64
+```
+
+Or prefix every build command:
+
+```bash
+LIBCLANG_PATH=/usr/lib64/llvm21/lib64 npm run tauri dev
+```
+
+### Required (Vulkan GPU build)
+
+```bash
+sudo dnf install vulkan-headers vulkan-loader-devel glslc
+```
+
+| Package | Why |
+|---|---|
+| `vulkan-headers` | `vulkan.h` needed by ggml-vulkan CMake |
+| `vulkan-loader-devel` | `libvulkan.so` link target for CMake |
+| `glslc` | Compiles GLSL compute shaders to SPIR-V at build time |
+
+The NVIDIA Vulkan ICD (`nvidia_icd.json`) is included in the standard NVIDIA driver package — no extra install needed if the driver is already installed.
+
+---
+
+## Node / Rust
+
+```bash
+npm install          # frontend deps — run once after clone
+```
+
+Rust toolchain managed by `rustup`. No extra steps needed beyond what Tauri requires.
+
+---
+
+## Launch commands
+
+### CPU build (default)
+
+```bash
+cd /home/jake/Documents/CORBEL-Projects/kon
+LIBCLANG_PATH=/usr/lib64/llvm21/lib64 npm run tauri dev
+```
+
+Once `set -Ux LIBCLANG_PATH` is in fish config, this becomes:
+
+```bash
+npm run tauri dev
+```
+
+### Vulkan GPU build
+
+Same command — the `whisper-vulkan` feature flag is already set in `crates/transcription/Cargo.toml`. First build compiles Vulkan compute shaders and takes longer than usual.
+
+Confirm GPU is active in startup logs:
+
+```
+whisper_backend_init_gpu: device 0: NVIDIA GeForce RTX 4070   ← GPU active
+```
+
+vs CPU fallback:
+
+```
+whisper_backend_init_gpu: device 0: CPU (type: 0)             ← no GPU
+```
+
+---
+
+## Startup log reference
+
+Normal startup sequence:
+
+```
+[startup] Wayland workaround: GDK_BACKEND=x11
+[startup] DB init: ~4ms
+[startup] Preferences load: ~200µs
+[startup] Whisper model pre-warmed successfully
+```
+
+The Wayland workarounds are injected automatically by `ensure_x11_on_wayland()` in `src-tauri/src/lib.rs` — no manual env-var prefix needed.
+
+---
+
+## Known build gotchas
+
+| Issue | Cause | Fix |
+|---|---|---|
+| `Unable to find libclang` | Fedora puts clang libs in versioned path | `set -Ux LIBCLANG_PATH /usr/lib64/llvm21/lib64` |
+| `Could NOT find Vulkan (missing: glslc)` | Shader compiler not installed | `sudo dnf install vulkan-headers vulkan-loader-devel glslc` |
+| `there is no reactor running` | `tokio::spawn` called before runtime starts in `setup()` | Use `tauri::async_runtime::spawn` instead |
+| `effect_update_depth_exceeded` | Svelte 5 `$state` object reassigned instead of mutated | Use `Object.assign(state, updates)` — never spread-replace module-level state |
+
+---
+
+## GPU notes
+
+- **Vulkan** is the GPU backend used here. CUDA is not required.
+- `crates/transcription/Cargo.toml` feature: `whisper-vulkan` → `whisper-rs/vulkan` → `ggml-vulkan`
+- CPU and GPU builds are otherwise identical — same binary, same model files.
+- Expected speedup on RTX 4070: ~10–15× over CPU for `whisper-base.en`.