# Development > **Status:** draft · **Last updated:** 2026-10-31 ## 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 - macOS: a step-by-step setup for a fresh Apple Silicon Mac is in [`macos.md`](macos.md) ## Everyday commands ```sh 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/ cargo xtask mac-report # gate, build and an app self-check, written to target/mac-report/report.md cargo xtask demo-project ../lutra-demo # offline demo project for docs/alpha-checklist.md cargo xtask bundle # this platform's installer (NSIS setup on Windows, DMG on macOS), see install.md cargo xtask installer-images # regenerate assets/installer/ from docs/images/banner.png ``` `mac-report` is made for checking a machine the developers cannot reach (the Mac, see [`macos.md`](macos.md)) but runs everywhere. Every step has a timeout; `--skip-gate` leaves out the gate, `--port` picks the control port (default 7971). ## Data directories A `--control PORT` instance keeps its settings, recovery journal and webview data in `/lutra-control//`, 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: ```sh 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=/debug/lutra-desktop.exe LUTRA_CONTROL_PORT= cargo test -p lutra-desktop --test screenshot_focus -- --ignored`. ## Build directories and parallel work - Keep `CARGO_TARGET_DIR` inside the repository folder: the default `target/`, or `/target` per 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_DIR` and 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: ```sh 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-31 | minor | B1: `cargo xtask bundle`, `cargo xtask installer-images` | | 2026-10-31 | minor | A2: `cargo xtask demo-project` | | 2026-10-31 | minor | A1: `cargo xtask mac-report`, link to the macOS setup | | 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 |