---
name: dev-setup
type: reference
tags: [setup, dependencies, build, linux, fedora]
description: 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)

```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. 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:

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

Or prefix one command if you are bypassing the launcher:

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

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

Canonical dev launch:

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

Direct shell equivalent:

```bash
./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:

```bash
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`.