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>
This commit is contained in:
parent
da58c83158
commit
1bf69ded55
18 changed files with 1795 additions and 36 deletions
221
docs/macos.md
Normal file
221
docs/macos.md
Normal file
|
|
@ -0,0 +1,221 @@
|
|||
# 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](#gatekeeper-and-code-signing)).
|
||||
|
||||
## 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`.
|
||||
|
||||
```sh
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
A window asks to install the tools: click **Install** and accept the licence. It takes a few minutes. Check it:
|
||||
|
||||
```sh
|
||||
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](https://brew.sh):
|
||||
|
||||
```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:
|
||||
|
||||
```sh
|
||||
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
|
||||
```
|
||||
|
||||
```sh
|
||||
eval "$(/opt/homebrew/bin/brew shellenv)"
|
||||
```
|
||||
|
||||
Check it:
|
||||
|
||||
```sh
|
||||
brew --version
|
||||
```
|
||||
|
||||
## 4. Git, PHP, Composer, Node and pnpm
|
||||
|
||||
```sh
|
||||
brew install git php composer node@22 pnpm
|
||||
```
|
||||
|
||||
`node@22` is "keg-only", so put it on the `PATH` yourself:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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](https://rustup.rs):
|
||||
|
||||
```sh
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Press Return to accept the default installation. Then load it into this window:
|
||||
|
||||
```sh
|
||||
. "$HOME/.cargo/env"
|
||||
```
|
||||
|
||||
Check it:
|
||||
|
||||
```sh
|
||||
rustc -V && cargo -V
|
||||
```
|
||||
|
||||
Optional, for the licence check of the gate (the report skips it without):
|
||||
|
||||
```sh
|
||||
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):
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
cat ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
Then clone into a folder of your choice, for example `~/Projekte`:
|
||||
|
||||
```sh
|
||||
mkdir -p ~/Projekte && cd ~/Projekte
|
||||
```
|
||||
|
||||
```sh
|
||||
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`.
|
||||
|
||||
```sh
|
||||
cd lutra
|
||||
```
|
||||
|
||||
## 7. The machine report
|
||||
|
||||
One command checks the Mac end to end and writes one file to send back:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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) |
|
||||
Loading…
Add table
Add a link
Reference in a new issue