Lumotia/docs/dev-setup.md

name, type, tags, description

name	type	tags	description
dev-setup	reference	setup dependencies build linux fedora	Authoritative build dependencies and launch instructions for Lumotia on Fedora Linux

Lumotia — Developer Setup

Last updated: 2026/05/12. Primary dev target: Fedora Linux, x86_64, KDE Wayland, NVIDIA RTX 4070.

---

System dependencies

Required (CPU build)

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. The dev launcher defaults LIBCLANG_PATH to that path on Linux, but a value you set in your shell wins.

To set it permanently in fish:

set -Ux LIBCLANG_PATH /usr/lib64/llvm21/lib64

Or prefix one command if you are bypassing the launcher:

LIBCLANG_PATH=/usr/lib64/llvm21/lib64 cargo check -p lumotia

Required (Vulkan GPU build)

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

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)

Canonical dev launch:

cd /home/jake/Documents/CORBEL-Projects/transcription-app
npm run dev:tauri

Direct shell equivalent:

./run.sh

run.sh starts Vite, waits for port 1420, then launches Tauri with its beforeDevCommand disabled so a second Vite instance does not race the first one.

On Linux, run.sh also owns the rendering environment contract expected by src-tauri/src/lib.rs::warn_if_x11_env_unset_on_wayland:

• WEBKIT_DISABLE_DMABUF_RENDERER=1 by default on Linux. Set WEBKIT_DISABLE_DMABUF_RENDERER=0 explicitly to opt out.
• GDK_BACKEND=x11 and WINIT_UNIX_BACKEND=x11 by default only when XDG_SESSION_TYPE=wayland.
• Any value already set in your shell wins because the launcher uses shell defaults (${VAR:-default}).

If you prefer shell-rc setup, these manual exports are equivalent on a Wayland session:

export WEBKIT_DISABLE_DMABUF_RENDERER="${WEBKIT_DISABLE_DMABUF_RENDERER:-1}"
export GDK_BACKEND="${GDK_BACKEND:-x11}"
export WINIT_UNIX_BACKEND="${WINIT_UNIX_BACKEND:-x11}"
npm run dev:tauri

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 Rust startup logs now come through tracing rather than raw eprintln!, so the exact timestamp/format depends on RUST_LOG and the subscriber formatter. Typical messages include:

INFO lumotia_startup: DB init complete elapsed_ms=4
INFO lumotia_startup: preferences load complete elapsed_ms=0
WARN lumotia_startup: Linux WebKitGTK microphone permission requests are auto-granted for audio-only capture; other permission classes remain denied

When launched through npm run dev:tauri / ./run.sh, you should not see lumotia_startup warnings containing:

Linux rendering workaround env var is not set

Those warnings mean the launcher contract was bypassed or broken.

---

Known build gotchas

Issue	Cause	Fix
Unable to find libclang	Fedora puts clang libs in versioned path	Use npm run dev:tauri / ./run.sh, or set 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.