Jake
26c7307607
Phase 9 of the rebrand cascade. Sweep covers everything the Phase 8
frontend pass deliberately skipped: docs/, root markdown, scripts,
Cargo.toml descriptions, code comments that survived earlier
word-boundary sed, plus a handful of identifiers caught on the final
verify pass.
transcription-app changes:
- README.md, HANDOVER.md, KNOWN-ISSUES.md, run.sh — magnotia/Magnotia
-> lumotia/Lumotia.
- docs/ — sweep across all subdirs except docs/handovers/ (preserved
as immutable audit trail). Includes architecture-map references
to magnotia_core::*, magnotia_storage::*, etc. now pointing at
lumotia_*; dev-setup.md tracing output examples (lumotia_startup
target); brief/ + superpowers/ + issues/ + whisper-ecosystem/ +
audit/.
- Cargo.toml descriptions on 9 crates (core, audio, cloud-providers,
hotkey, llm, mcp, plus referenced others).
- crates/core/src/{error,hardware,recommendation,paths}.rs +
crates/audio/src/wav.rs + crates/llm/src/model_manager.rs +
crates/cloud-providers/src/keystore.rs + crates/mcp/src/lib.rs —
doc comments and a model-manager user-agent string.
- Caught on final pass: BroadcastChannel("magnotia_task_sync") -> ...
("lumotia_task_sync"); magnotia_locale i18n localStorage key
renamed + migration shim added; CSS keyframe names
magnotiaPulse / magnotiaBar / magnotiaFade renamed in the design-
system kit; magnotia_viewer_item / magnotia_viewer_mode handoff
keys renamed in HistoryPage + viewer/+page.svelte; src/assets/
wordmark.svg text.
- src-tauri/src/lib.rs comment cleanup ("magnotia era" was sed'd
to "lumotia era" earlier — restored).
Preserved (intentional):
- crates/core/src/paths.rs — keeps "magnotia" / "Magnotia" / ".magnotia"
legacy detection strings in legacy_and_target_paths() so the
migration shim can still find user data from the magnotia era.
- src/lib/stores/{page,focusTimer}.svelte.ts + src/lib/i18n/index.ts
— migration call sites reference the legacy magnotia keys
deliberately.
- docs/handovers/ — historical audit trail.
cargo build --workspace passes. npm run check: 0 errors / 0 warnings
(3958 files). cargo test --workspace: 339 pass / 0 fail.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
156 lines
4.8 KiB
Markdown
156 lines
4.8 KiB
Markdown
---
|
||
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`.
|