Lutra/docs/macos.md
danny 1bf69ded55 A1: macOS readiness: setup guide, cargo xtask mac-report, unix/macOS fixes
- 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>
2026-10-31 14:47:45 +01:00

10 KiB
Raw Blame History

macOS

Status: draft, written without a Mac, not yet run on one · Last updated: 2026-10-31

How to set up a fresh Apple Silicon Mac (M1 or newer, macOS 14 Sonoma or newer) to build, test and run Lutra from source, and how to send a machine report back to the developers. Follow the steps in order and type the commands exactly as shown; each one is a single line for the Terminal.

Lutra is not signed or notarised yet, and there is no installer (DMG). You build it yourself, which is fine for the alpha: a program you build on your own Mac is not quarantined, so Gatekeeper does not block it (see Gatekeeper).

1. Open Terminal

Press ⌘ Space, type Terminal, press Return. Everything below happens in that window. The shell is zsh, the macOS default.

2. Xcode Command Line Tools

The compiler and linker that Rust uses, plus Apple's git.

xcode-select --install

A window asks to install the tools: click Install and accept the licence. It takes a few minutes. Check it:

xcode-select -p

It prints /Library/Developer/CommandLineTools (or a path inside Xcode.app if you have full Xcode; that works too). If it says the tools are already installed, go on.

3. Homebrew

The package manager for PHP, Node and the rest. Install it with the command from brew.sh:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

It asks for your Mac password (typing shows nothing; that is normal). At the end it prints Next steps with two commands that put Homebrew on your PATH. On Apple Silicon they are:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Check it:

brew --version

4. Git, PHP, Composer, Node and pnpm

brew install git php composer node@22 pnpm

node@22 is "keg-only", so put it on the PATH yourself:

echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zprofile

Then close the Terminal window and open a new one, so the new PATH applies. Check the versions:

git --version && php -v && composer --version && node -v && pnpm -v

You need git 2.30 or newer, PHP 8.2 or newer, Node 22.12 or newer and pnpm 10. Homebrew's git is newer than Apple's; both work.

5. Rust

Install rustup, the Rust installer, from rustup.rs:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Press Return to accept the default installation. Then load it into this window:

. "$HOME/.cargo/env"

Check it:

rustc -V && cargo -V

Optional, for the licence check of the gate (the report skips it without):

cargo install cargo-deny --locked

This compiles for a few minutes.

6. Get the code

Lutra lives on Daniel's Forgejo server and is cloned over SSH. If this Mac has no SSH key for it yet, create one and add the public key to your Forgejo account (Settings ▸ SSH / GPG Keys ▸ Add Key):

ssh-keygen -t ed25519 -C "lutra-mac"

Press Return three times (default file, no passphrase, or set one if you like). Show the public key to copy it:

cat ~/.ssh/id_ed25519.pub

Then clone into a folder of your choice, for example ~/Projekte:

mkdir -p ~/Projekte && cd ~/Projekte
git clone ssh://git@git.daniel-diekert.com:2222/daniel/Lutra.git lutra

The first connection asks whether to trust the server's host key: type yes.

cd lutra

7. The machine report

One command checks the Mac end to end and writes one file to send back:

cargo xtask mac-report

It runs, with a timeout on every step so it never hangs:

  1. the versions of macOS, the Command Line Tools, Rust, Node, pnpm, git, PHP and Composer;
  2. the quality gate: cargo fmt, cargo clippy, cargo test, the project checks, cargo deny (skipped without cargo-deny) and the frontend's lint, typecheck and tests;
  3. the frontend build and a build of the desktop app with the UI bundled in;
  4. one start of the app with a fresh, separate data folder and the control channel on port 7971, and a self-check through it: open a small demo project, open a PHP file, wait for Phpactor (the language server is downloaded on first use, which needs the internet), a hover, git.status, a terminal that runs a command, a screenshot, and quitting the app.

The first run takes a while (about 20–40 minutes, mostly compiling); later runs are much faster. The Lutra window opens for a minute near the end, in the background; leave it alone and it closes itself.

When it finishes it prints where the report is:

mac-report: report written to /Users/<you>/Projekte/lutra/target/mac-report/report.md

Send back target/mac-report/report.md and target/mac-report/screenshot.png. If a step failed, also zip and send the target/mac-report/logs folder. A failure does not stop the report; failed steps are listed with their error text.

Options:

  • cargo xtask mac-report --skip-gate: only the build and the app self-check (about 10 minutes the first time). Useful after a fix to the app.
  • --port 7972: another control port, if 7971 is taken.
  • --out DIR: write the report somewhere else.

Screen Recording permission

The screenshot step captures the Lutra window from the screen. The first time, macOS may ask whether Terminal may record the screen. Click Open System Settings and turn on Terminal under Privacy & Security ▸ Screen & System Audio Recording, then run the report again. If you decline, only the screenshot step fails.

8. Running Lutra by hand

For the alpha checklist, start the app from the repository folder:

cargo xtask dev

The first time this asks for the Tauri CLI; install it with cargo install tauri-cli --locked. Or run the self-contained build the report made:

target/debug/lutra-desktop ~/Projekte/some-php-project

Gatekeeper and code signing

  • Built on this Mac: files you compile yourself (with cargo) carry no quarantine attribute, and the Apple Silicon linker signs them ad hoc automatically, so they run without any Gatekeeper prompt. That covers everything in this guide.

  • Copied from elsewhere: a Lutra binary downloaded with a browser, AirDrop or a chat app is quarantined, and because it is not notarised, macOS refuses to open it ("cannot be opened because Apple cannot check it for malicious software"). Only for a build you trust, remove the quarantine attribute:

    xattr -dr com.apple.quarantine /path/to/lutra-desktop
    

    Or open it once with a right click ▸ Open (on macOS 15 and later: try to open it, then System Settings ▸ Privacy & Security ▸ Open Anyway).

  • Phpactor: Lutra downloads the Phpactor PHAR itself and checks its SHA-256; files that Lutra writes are not quarantined, and PHP runs the PHAR, so Gatekeeper is not involved.

  • Real signing and notarisation need an Apple Developer ID and the final app identifier (open owner decision O2); they come with the installers, after the alpha.

What is different on macOS

  • Menu bar. Lutra's own menu is inside the window, as on Windows. The macOS menu bar has the Lutra menu (About, Hide, Quit), Edit (Undo, Redo, Cut, Copy, Paste, Select All: macOS web views need these for the clipboard keys) and Window (Minimize, Zoom, Full Screen). ⌘W closes the editor tab, not the window, and ⌘Q quits through Lutra's own Quit (terminals closed, the language server shut down).
  • Shortcuts. Mod in Lutra's keymap is ⌘ on macOS and Ctrl elsewhere.
  • Terminal. The integrated terminal starts your login shell ($SHELL, normally zsh) with -l, as Terminal.app does, so ~/.zprofile runs and Homebrew's PHP and Composer are on the PATH even when Lutra was started from the Finder or Dock. Without a locale in the environment it sets LANG=en_US.UTF-8.
  • PHP. Lutra finds PHP on the PATH and, after it, in /opt/homebrew/bin, /usr/local/bin and /opt/local/bin, because an app started from the Finder only gets the system PATH. The setting php.executable overrides both.
  • Data. Settings, the recovery journal and the downloaded Phpactor live in ~/Library/Application Support/dev.lutra.desktop/. An instance started with --control or --data-dir (as the report does) uses its own folder and shares only the Phpactor download.
  • File names. The default APFS volume ignores case, like Windows, so paths the language server reports are matched to project files without regard to case.

What was checked without a Mac

The developers have no Mac. On 2026-10-31 (A1), cargo check --all-targets --target aarch64-apple-darwin ran on Windows for every crate:

  • passed: lutra-text, lutra-proc (its Unix process groups and watchdog), lutra-vfs, lutra-terminal (PTY, default shell, locale), lutra-vcs, xtask (mac-report);
  • cannot be checked from Windows: every crate that depends on a C build script needs a C compiler and the macOS SDK: ring (TLS for the Phpactor download) for lutra-search, lutra-lsp, lutra-index, lutra-control, lutra-engine, lutra-mcp and lutra-cli; tree-sitter for lutra-syntax; objc2-exception-helper for lutra-desktop. Most of their macOS-specific code uses cfg!(target_os = "macos") inside ordinary code, so the Windows build type-checks it anyway; only the xcap screenshot module (#[cfg(not(windows))]) is compiled on the Mac alone.
  • cargo xtask mac-report --skip-gate ran green on Windows (build, app start, project, file, Phpactor, hover, git, terminal, screenshot, quit).

These can only be checked on the Mac itself, which is what the report does:

  • everything that builds C or Objective-C code (the desktop app with Tauri, WKWebView and xcap; the terminal's PTY layer links against the system);
  • the Unix process groups and the /bin/sh watchdog of lutra_proc at run time (they are the same as on Linux, where the tests passed earlier);
  • the PTY, the login shell and the screenshot on a Retina display;
  • the menu bar and its keys.

Revision history

Date Change Summary
2026-10-31 major A1: initial guide (setup, cargo xtask mac-report, Gatekeeper, macOS differences, what Windows cannot check)