3.4 KiB
Development
Status: draft · Last updated: 2026-10-27
Prerequisites
- Rust stable (via rustup), edition 2024
- Node.js 22.12 or newer (Vite 8 needs it) and pnpm 10
- Tauri 2 system prerequisites for your platform (WebView2 on Windows, WebKitGTK on Linux)
- Optional: Phpactor on the PATH for language features, PHP 8.2+ and Composer for reference projects
Everyday commands
cargo xtask dev # run the app in development mode
cargo xtask dev -- --control 7979 . # with the JSON control channel
cargo xtask ci # the full quality gate, run before every commit
cargo xtask fixtures # create Symfony and Laravel reference projects in target/fixtures/
Data directories
A --control PORT instance keeps its settings, recovery journal and webview data in <temp>/lutra-control/<port>/, never in your own data directory, so a dev or agent instance cannot change your settings or restore your journal. --data-dir DIR or LUTRA_DATA_DIR=DIR pick another directory, for any instance:
cargo run -p lutra-desktop -- --control 7979 --data-dir target/lutra-data .
Delete the folder to start fresh. Its window opens without taking the foreground, and ui.screenshot never focuses it; only app.focus does. To check that on Windows, build with --features bundled-ui and run LUTRA_DESKTOP_EXE=<target>/debug/lutra-desktop.exe LUTRA_CONTROL_PORT=<port> cargo test -p lutra-desktop --test screenshot_focus -- --ignored.
Build directories and parallel work
- Keep
CARGO_TARGET_DIRinside the repository folder: the defaulttarget/, or<worktree>/targetper git worktree (/target/is gitignored). Antivirus exclusions usually cover the checkout. On Windows, unsigned binaries built outside an excluded folder have taken about 26 s to start each child process (Phpactor, git, the test helpers) against 28 ms inside, which makes tests time out. - Several builds in parallel (agents, worktrees): give each its own
CARGO_TARGET_DIRand limit the jobs, e.g.CARGO_BUILD_JOBS=4. Delete a worktree's target directory once its work is merged; a full build takes about 10 GB.
Deleting ui/node_modules
pnpm hardlinks packages from its shared store. Deleting ui/node_modules with Git Bash rm -rf on Windows breaks those links for other checkouts and makes their running Vitest fail with EBUSY. Delete it with either of:
cmd //c "rmdir /s /q ui\node_modules"
node -e "require('fs').rmSync('ui/node_modules',{recursive:true,force:true})"
Then run pnpm --dir ui install again.
Robustness: Lutra never crashes
Shipped code returns errors instead of panicking (see AGENTS.md › Never crash). The engine guard catches panics at every entry point, keeps buffers intact and reports an internal error. Unsaved buffers are journaled so a restart can restore them.
Code style
No inline comments. Doc comment blocks above modules, functions, types and fields explain purpose, parameters, return values and errors.
Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-27 | minor | F3: data directories, build directories inside the repository, parallel builds, deleting ui/node_modules |
| 2026-10-27 | minor | Unfocused --control windows and the screenshot focus check (F2) |
| 2026-10-25 | minor | Isolated data directory for --control instances (H6) |
| 2026-10-14 | minor | Node.js 22.12+ required by the frontend toolchain |
| 2026-10-13 | major | Initial draft |