C2: lutra CLI in the setup with optional PATH entry, xtask bundle prints the version
- xtask bundle builds lutra-cli and adds it as a Tauri external binary through a --config override (lutra.exe next to the app on Windows, Lutra.app/Contents/MacOS/lutra on macOS); prints path, version, size. - NSIS: "Add lutra to PATH" page, unticked by default, /ADDTOPATH for silent installs. Changes HKCU\Environment Path only, keeps its type, broadcasts WM_SETTINGCHANGE, records the entry; the uninstaller removes exactly that entry. A PATH too long for NSIS strings is left alone. - lutra CLI resolves a symlinked executable before looking for the app. - localStorage: the UI never used webview storage, so there is nothing to migrate; docs corrected, ESLint now bans localStorage, sessionStorage and indexedDB, with tests. - docs/install.md: CLI, PATH, macOS link step, webview folder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
d8e66a4652
commit
0a4b80adec
7 changed files with 628 additions and 46 deletions
|
|
@ -1,10 +1,10 @@
|
|||
# Installing Lutra
|
||||
|
||||
> **Status:** draft, alpha installers · **Last updated:** 2026-10-31
|
||||
> **Status:** draft, alpha installers · **Last updated:** 2026-11-01
|
||||
|
||||
Lutra's alpha comes as an installer for Windows (a setup `.exe`) and macOS (a `.dmg`). Both are **not signed yet**, so Windows and macOS warn before the first start; the steps below get past that once. Linux has no installer yet: build it from source ([`development.md`](development.md)).
|
||||
|
||||
The installers contain the desktop app only. The `lutra` command-line tool (`lutra .`, `lutra mcp`) is not in them yet; build it with `cargo build --release -p lutra-cli` if you need it.
|
||||
Both installers contain the desktop app and the `lutra` command-line tool (`lutra file.php`, `lutra .`, `lutra mcp`). On Windows the setup can put `lutra` on your PATH; on macOS you link it once (see [Using `lutra` from a terminal](#using-lutra-from-a-terminal)).
|
||||
|
||||
## Building an installer
|
||||
|
||||
|
|
@ -14,7 +14,7 @@ On the platform you want the installer for:
|
|||
cargo xtask bundle
|
||||
```
|
||||
|
||||
It builds the release app with the bundled UI and prints the installer's path and size: `target/release/bundle/nsis/Lutra_<version>_x64-setup.exe` on Windows, `target/release/bundle/dmg/Lutra_<version>_aarch64.dmg` on macOS. It needs the Tauri CLI (`cargo install tauri-cli --locked`) and, on macOS, the Xcode Command Line Tools ([`macos.md`](macos.md)).
|
||||
It builds the `lutra` CLI and the release app with the bundled UI, packs both, and prints the installer's path, the version and the size, for example `bundle: Lutra 0.1.0-alpha: C:\…\target\release\bundle\nsis\Lutra_0.1.0-alpha_x64-setup.exe (5.4 MB)`. The installer is `target/release/bundle/nsis/Lutra_<version>_x64-setup.exe` on Windows and `target/release/bundle/dmg/Lutra_<version>_aarch64.dmg` on macOS. The version comes from `apps/lutra-desktop/tauri.conf.json`. It needs the Tauri CLI (`cargo install tauri-cli --locked`) and, on macOS, the Xcode Command Line Tools ([`macos.md`](macos.md)).
|
||||
|
||||
## Windows
|
||||
|
||||
|
|
@ -22,12 +22,26 @@ Lutra installs for your user only: no administrator rights, no UAC prompt. It ne
|
|||
|
||||
1. Start `Lutra_<version>_x64-setup.exe`.
|
||||
2. Windows SmartScreen says "Windows protected your PC", because the setup is not signed. Click **More info**, check that the app is `Lutra_<version>_x64-setup.exe` and the publisher is "Unknown publisher", then click **Run anyway**. If you downloaded the file with a browser, the browser may ask first whether to keep it.
|
||||
3. The setup runs in English or German, following Windows. Click **Next**, keep or change the folder (default `%LOCALAPPDATA%\Lutra`), click **Install**.
|
||||
4. On the last page, tick **Create desktop shortcut** if you want one, keep or clear **Run Lutra**, and click **Finish**. The setup closes at once; Lutra starts through Explorer a moment later.
|
||||
3. The setup runs in English or German, following Windows. Click **Next** and keep or change the folder (default `%LOCALAPPDATA%\Lutra`).
|
||||
4. On the **Command line** page, tick **Add lutra to PATH** if you want to run `lutra` in a terminal. It is off by default. Click **Next**, then **Install**.
|
||||
5. On the last page, tick **Create desktop shortcut** if you want one, keep or clear **Run Lutra**, and click **Finish**. The setup closes at once; Lutra starts through Explorer a moment later.
|
||||
|
||||
Lutra is now in the Start menu as **Lutra** and in Settings → Apps → Installed apps. Installing a newer setup over it updates it in place and keeps your settings.
|
||||
|
||||
For scripts: `Lutra_<version>_x64-setup.exe /S` installs silently with both shortcuts, `/P` shows only the progress bar, `/D=C:\path` (last argument) picks the folder, `/NS` skips the shortcuts, `/R` starts Lutra afterwards.
|
||||
For scripts: `Lutra_<version>_x64-setup.exe /S` installs silently with both shortcuts, `/P` shows only the progress bar, `/ADDTOPATH` adds `lutra` to the PATH, `/D=C:\path` (last argument) picks the folder, `/NS` skips the shortcuts, `/R` starts Lutra afterwards.
|
||||
|
||||
### Using `lutra` from a terminal
|
||||
|
||||
The setup installs `lutra.exe` next to `lutra-desktop.exe` in the install folder. With **Add lutra to PATH** ticked, the setup appends the install folder to your user PATH (`HKCU\Environment`, value `Path`; the system PATH is not touched) and tells Windows the environment changed. Terminals opened afterwards find it:
|
||||
|
||||
```bat
|
||||
lutra src\Controller\HomeController.php:42
|
||||
lutra .
|
||||
```
|
||||
|
||||
`lutra <file>` opens the file in the running Lutra, inside the project around it (see below); if Lutra is not running, it starts it first. Without the PATH entry, call it by its full path: `%LOCALAPPDATA%\Lutra\lutra.exe file.php`.
|
||||
|
||||
The setup notes the folder it added (value `PathEntry` under `HKCU\Software\Lutra\Lutra`). Running a newer setup keeps the entry; clearing the box there removes it. The uninstaller removes exactly that entry and leaves the rest of your PATH as it was. If the folder was on your PATH before the setup ran, the setup does not add it a second time and the uninstaller leaves it alone. A user PATH too long for the setup to edit safely (about 1000 characters) is not changed; the setup says so, and you can add the folder by hand.
|
||||
|
||||
### Opening PHP files from Explorer
|
||||
|
||||
|
|
@ -47,7 +61,7 @@ Since 0.1.0-alpha the finish page starts Lutra through Explorer (`explorer.exe "
|
|||
|
||||
### Uninstalling on Windows
|
||||
|
||||
Settings → Apps → Installed apps → **Lutra** → … → **Uninstall**, or run `uninstall.exe` in the install folder. The uninstaller removes the app, its shortcuts, its Installed-apps entry and the **Open with** entries. Your settings, recovery journal and Phpactor stay unless you tick **Delete the application data**.
|
||||
Settings → Apps → Installed apps → **Lutra** → … → **Uninstall**, or run `uninstall.exe` in the install folder. The uninstaller removes the app and `lutra.exe`, its shortcuts, its Installed-apps entry, the **Open with** entries and the PATH entry the setup added. Your settings, recovery journal and Phpactor stay unless you tick **Delete the application data**.
|
||||
|
||||
## macOS
|
||||
|
||||
|
|
@ -63,6 +77,17 @@ xattr -dr com.apple.quarantine /Applications/Lutra.app
|
|||
|
||||
You need to do this once per installed version.
|
||||
|
||||
### Using `lutra` from a terminal on macOS
|
||||
|
||||
The CLI is inside the app, at `/Applications/Lutra.app/Contents/MacOS/lutra`. Link it once into a folder on your PATH, for example:
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.local/bin
|
||||
ln -sf /Applications/Lutra.app/Contents/MacOS/lutra ~/.local/bin/lutra
|
||||
```
|
||||
|
||||
`~/.local/bin` must be on your PATH (add `export PATH="$HOME/.local/bin:$PATH"` to `~/.zshrc` if it is not). `/usr/local/bin` works too, with `sudo`. The link follows updates, because a new version replaces the app at the same place. Remove the quarantine flag first (step 3 above), or macOS blocks the unsigned `lutra` binary as well. To remove it again: `rm ~/.local/bin/lutra`.
|
||||
|
||||
### Opening PHP files from Finder
|
||||
|
||||
Lutra registers as an alternate editor for `.php`, `.phtml`, `.phpt` and `.inc` files: it appears under **Open With** without becoming the default. A file opens as on Windows, in the project around it.
|
||||
|
|
@ -77,11 +102,11 @@ Quit Lutra and drag **Lutra** from **Applications** to the Trash. Your data stay
|
|||
|---|---|---|
|
||||
| The app | `%LOCALAPPDATA%\Lutra\` | `/Applications/Lutra.app` |
|
||||
| Settings (`settings.json`), recovery journal (`recovery\`), downloaded Phpactor (`tools\`) | `%APPDATA%\com.tyrveil.lutra\` | `~/Library/Application Support/com.tyrveil.lutra/` |
|
||||
| Window data of the web view (recent projects, layout) | `%LOCALAPPDATA%\com.tyrveil.lutra\` | `~/Library/WebKit/com.tyrveil.lutra/`, `~/Library/Caches/com.tyrveil.lutra/` |
|
||||
| The web view's caches (no settings or other state of yours) | `%LOCALAPPDATA%\com.tyrveil.lutra\` | `~/Library/WebKit/com.tyrveil.lutra/`, `~/Library/Caches/com.tyrveil.lutra/` |
|
||||
|
||||
On Linux, when built from source: settings in `~/.config/com.tyrveil.lutra/`, journal and tools in `~/.local/share/com.tyrveil.lutra/`.
|
||||
|
||||
**From a build before the installers.** Earlier builds used the identifier `dev.lutra.desktop`. The first start of a new build copies `settings.json`, the recovery journal and the downloaded Phpactor from the old `dev.lutra.desktop` folders once and shows a notification; the old folders stay untouched and can be deleted afterwards. Recent projects and the window layout are not copied.
|
||||
**From a build before the installers.** Earlier builds used the identifier `dev.lutra.desktop`. The first start of a new build copies `settings.json`, the recovery journal and the downloaded Phpactor from the old `dev.lutra.desktop` folders once and shows a notification; the old folders stay untouched and can be deleted afterwards. The web view's old folder (`%LOCALAPPDATA%\dev.lutra.desktop\`, `~/Library/WebKit/dev.lutra.desktop/`) holds only caches: Lutra keeps nothing in the web view's storage, so nothing is lost there, and it can be deleted too.
|
||||
|
||||
An instance started with `--control PORT` or `--data-dir DIR` keeps its files in its own folder (see [`development.md`](development.md#data-directories)).
|
||||
|
||||
|
|
@ -91,3 +116,4 @@ An instance started with `--control PORT` or `--data-dir DIR` keeps its files in
|
|||
|---|---|---|
|
||||
| 2026-10-31 | major | B1: initial version, NSIS setup and DMG, unsigned |
|
||||
| 2026-10-31 | minor | B2: finish-page hang found and fixed, Open with for PHP files, version 0.1.0-alpha |
|
||||
| 2026-11-01 | minor | C2: `lutra` CLI in both installers, optional per-user PATH entry on Windows, macOS link step, `xtask bundle` prints the version; the web view's folder holds no user state |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue