- App identifier com.tyrveil.lutra (D26) in tauri.conf.json and rendezvous::APP_IDENTIFIER; a test keeps them equal. - First normal start copies settings.json, recovery/ and tools/ once from the dev.lutra.desktop directories (staging dir + rename, logged, info notification); old directories stay untouched. - Bundling on: per-user NSIS setup (English, German, Start menu, optional desktop shortcut, uninstaller) and DMG; `cargo xtask bundle` builds the platform's installer, joining the DMG backgrounds into a HiDPI TIFF on macOS. build.rs also writes icons/512x512.png for the .icns. - Installer images from the banner, designed by Amy, generated by `cargo xtask installer-images` (assets/installer/, ASSETS.md rows); approved by Daniel. - docs/install.md (SmartScreen, Gatekeeper, uninstall, data locations), README install section, architecture, development and macOS notes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
73 lines
4.3 KiB
Markdown
73 lines
4.3 KiB
Markdown
# 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 `<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:
|
||
|
||
```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=<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_DIR` inside the repository folder: the default `target/`, or `<worktree>/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 |
|