Lutra/docs/development.md
danny bd225d9e3a B1: alpha installers (NSIS, DMG), identifier com.tyrveil.lutra with data migration
- 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>
2026-10-31 21:48:15 +01:00

4.3 KiB
Raw Permalink Blame History

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
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) 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_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:

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