- docs/macos.md: step-by-step setup for a fresh Apple Silicon Mac (Xcode CLT, Homebrew, git, PHP, Composer, Node 22, pnpm, rustup, clone from Forgejo), the machine report, Gatekeeper notes, macOS differences and what Windows cannot check. - cargo xtask mac-report: versions, the gate steps, the bundled-UI desktop build and a self-check over the control channel (project, file, Phpactor, hover, git.status, terminal, screenshot, quit); every step times out and runs in a lutra_proc group; one report.md to send back. - Fixes: macOS native menu (system menus only; Cmd+W stays buffer.close, Cmd+Q runs app.quit), xcap screenshot region in points on macOS (Retina), login shell (-l, /bin/zsh fallback) and LANG for the terminal on macOS, PHP lookup in Homebrew/MacPorts dirs for Finder starts, case-insensitive LSP path mapping on macOS, rendezvous file mode re-set to 0600, CLI-started desktop in its own process group. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.9 KiB
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
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/
cargo xtask mac-report # gate, build and an app self-check, written to target/mac-report/report.md
mac-report is made for checking a machine the developers cannot reach (the Mac, see 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 <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-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 |