Lutra/docs/install.md
danny b17d26b400
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run
B2: setup finish without hang, Open with for PHP files, 0.1.0-alpha
- Finish page starts Lutra through Explorer (Exec, returns at once)
  instead of RunAsUser/ShellExecute on the setup's UI thread. The 0.0.0
  setup hung there while the new, unsigned exe was checked (Norton 360
  active); Windows ended it and left lutra-desktop.exe suspended.
  The NSIS template is an adapted copy of tauri-bundler 2.10.2's.
- installer/hooks.nsh registers Lutra only under OpenWithProgids and
  Applications\lutra-desktop.exe for .php/.phtml/.phpt/.inc; the
  default app stays. The uninstaller removes exactly those entries.
  macOS gets an Alternate-rank CFBundleDocumentTypes entry and handles
  RunEvent::Opened.
- A file path argument opens the file inside its Git/Composer root (or
  folder); a running instance takes it over, switching projects only
  when the file lies outside (never over unsaved changes).
- Version 0.1.0-alpha in the workspace, tauri.conf.json and ui; a test
  keeps tauri.conf.json in step with the crate version.
- xtask bundle passes CARGO_TARGET_DIR to the Tauri CLI as an absolute
  path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 22:37:56 +01:00

7.8 KiB

Installing Lutra

Status: draft, alpha installers · Last updated: 2026-10-31

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).

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.

Building an installer

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).

Windows

Lutra installs for your user only: no administrator rights, no UAC prompt. It needs Microsoft Edge WebView2, which Windows 10 and 11 already have; if it is missing, the setup downloads it.

  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.

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.

Opening PHP files from Explorer

The setup offers Lutra in Explorer's Open with menu for .php, .phtml, .phpt and .inc files. It does not become the default app: double-clicking a PHP file still opens whatever opened it before. To make Lutra the default, pick Open with → Choose another app → Lutra and tick Always.

A file opened this way opens in a tab, inside the project around it: the nearest folder above it that is a Git repository, else the nearest one with a composer.json, else the file's own folder. If Lutra is already running, the running window takes the file. A file outside its open project switches the project; if the open project has unsaved changes, Lutra refuses to switch and nothing is lost. The same works from a terminal: lutra-desktop.exe C:\path\to\file.php.

If the setup stops responding on the last page

Seen once, with the 0.0.0 setup on a PC with Norton 360: after Finish with "Run Lutra" ticked, the setup window stopped responding, Windows closed it ("has stopped interacting with Windows", event AppHangB1), and Lutra did not open. What we found:

  • The 0.0.0 setup started Lutra with Tauri's RunAsUser helper, which calls ShellExecute on the setup's window thread. The new lutra-desktop.exe process was created suspended (one thread, wait reason "Suspended", no CPU time, no window) while the freshly written, unsigned exe was being checked, and the setup waited inside that call. When Windows ended the hanging setup, nothing resumed the process: it stayed in Task Manager as a lutra-desktop.exe without a window.
  • The same kind of build installed on the same PC without a hang, by hand and from a script. The stall depends on the check of a new, unknown file and could not be reproduced on demand. Norton 360 was active; its settings were not changed.
  • In that run the Installed-apps entry (HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Lutra) was missing and HKCU\Software\Lutra\Lutra still pointed to an older test install, although the files, uninstall.exe and the Start-menu shortcut were written. Every later install on the same PC wrote both keys correctly; why they were missing in that one run is not known.

Since 0.1.0-alpha the finish page starts Lutra through Explorer (explorer.exe "<install folder>\lutra-desktop.exe") and returns at once, so the setup no longer waits for those checks, and a slow check delays only Lutra's start. If you still find a lutra-desktop.exe without a window after a setup, end it in Task Manager and start Lutra from the Start menu. If Lutra is missing from Installed apps, run the setup again: it writes the entry anew.

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.

macOS

The DMG holds the app for Apple Silicon (M1 or newer), macOS 11 or newer.

  1. Open Lutra_<version>_aarch64.dmg and drag Lutra onto Applications. Eject the DMG.
  2. The first start is blocked because the app is not signed or notarised. In Applications, right-click (or Control-click) Lutra → Open, and click Open in the dialog. On macOS 15 Sequoia and newer that dialog has no Open button: click Done, then open System Settings → Privacy & Security, scroll to "Lutra was blocked", click Open Anyway and confirm with your password.
  3. Alternatively, remove the quarantine flag once in Terminal and start Lutra normally:
xattr -dr com.apple.quarantine /Applications/Lutra.app

You need to do this once per installed version.

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.

Uninstalling on macOS

Quit Lutra and drag Lutra from Applications to the Trash. Your data stays; delete the folders below to remove it.

Where your data lives

What Windows macOS
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/

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.

An instance started with --control PORT or --data-dir DIR keeps its files in its own folder (see development.md).

Revision history

Date Change Summary
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