All checks were successful
Validate Kaleido Desktop / validate (push) Successful in 1m22s
Fix a UI-thread deadlock between the player and window resizes: player_rect held the video-surface lock while Tauri's hwnd() waited for the UI thread, and on_resize, running on the UI thread, waited for that lock. Leaving full screen for the miniplayer could freeze the window while mpv kept playing. Resize handling now runs off the UI thread, and the Windows surface keeps its HWND instead of asking the UI thread for it. Add local diagnostics: a watchdog writes a dump of every thread when the UI thread stops answering for 5 s, unhandled exceptions write a crash dump and log the faulting module (Windows), and panics are logged. Windows release builds keep function names in kaleido.pdb, archived per version in .tools/symbols/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
147 lines
8.2 KiB
Markdown
147 lines
8.2 KiB
Markdown
# Development
|
||
|
||
## Setup (Windows)
|
||
|
||
1. Node 22+, Rust stable (MSVC), Visual Studio C++ build tools, 7-Zip.
|
||
2. `npm ci`
|
||
3. `.\scripts\fetch-libmpv.ps1` downloads the shinchiro `mpv-dev-x86_64` build (the
|
||
Windows libmpv builds linked from mpv.io) into `vendor/mpv/windows`.
|
||
4. Put a `.env` in the repository root for the development sign-in:
|
||
`PLEX_SERVER_URL=...` and `PLEX_TOKEN=...`. It is ignored by git and only read by
|
||
debug builds and the Vite dev server. Never commit or print it.
|
||
5. `npm run tauri dev`
|
||
|
||
## Setup (macOS)
|
||
|
||
1. Node 22+, Rust stable (`brew install rustup && rustup default stable`), the Xcode
|
||
command line tools and Homebrew.
|
||
2. `npm ci`
|
||
3. `sh scripts/fetch-libmpv.sh` installs Homebrew's `mpv` and copies libmpv with every
|
||
library it links into `vendor/mpv/macos`, rewritten to find each other there
|
||
(`@loader_path`) and signed, so the bundle doesn't depend on Homebrew. Homebrew
|
||
builds for the macOS it runs on, so the app's minimum macOS is that of the build
|
||
machine (`scripts/build.sh` sets it from the libraries).
|
||
4. `.env` as on Windows, then `npm run tauri dev`.
|
||
|
||
Debug builds on macOS keep the Plex token in `dev-secrets.json` in the app data folder
|
||
rather than the Keychain: every rebuild is a new unsigned binary, which the Keychain
|
||
would ask about again. Release builds always use the Keychain.
|
||
|
||
The interface alone runs in a browser with `npm run dev` (port 1420), which is handy for
|
||
layout work; playback, downloads and native dialogs need the desktop app. In development
|
||
builds the stores are available as `window.__kaleido` for debugging.
|
||
|
||
To drive the desktop app from scripts, start it with
|
||
`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333` and attach over the
|
||
Chrome DevTools Protocol.
|
||
|
||
## Checks
|
||
|
||
```powershell
|
||
npm run typecheck
|
||
npm test
|
||
cargo check --manifest-path src-tauri/Cargo.toml
|
||
```
|
||
|
||
Playback tests change real Plex progress; resume an in-progress title near its saved
|
||
position, or restore it afterwards. Selecting audio or subtitle tracks is saved to Plex
|
||
for that file.
|
||
|
||
## Diagnostics
|
||
|
||
`src-tauri/src/diagnostics.rs` writes to the app's log folder
|
||
(`%LOCALAPPDATA%\tv.kaleido.desktop\logs` on Windows); nothing is uploaded.
|
||
|
||
- **Hangs**: a watchdog asks the UI thread to answer every second. After 5 seconds of
|
||
silence it writes `kaleido-hang-<time>-v<version>.dmp` with every thread's stack (once
|
||
per stall) and notes the stall and the recovery in `diagnostics.log`.
|
||
- **Crashes** (Windows): an unhandled exception writes `kaleido-crash-…dmp` and logs the
|
||
exception and faulting module, e.g. `access violation at libmpv-2.dll+0x1234`.
|
||
- **Panics** are logged with a backtrace.
|
||
|
||
The newest five dumps of each kind are kept. To read one, open it in WinDbg with the
|
||
symbols of the exact build that wrote it: `scripts/build.ps1` keeps each release's
|
||
`kaleido.exe` and `kaleido.pdb` in `.tools/symbols/<version>/` (release builds keep
|
||
function names and line tables in the `.pdb`; the installer doesn't change). In WinDbg:
|
||
`.sympath+ <that folder>`, `.reload`, then `~*k` for every thread's stack.
|
||
|
||
Development builds have two test commands: `debug_freeze_ui` (`{ seconds }`, holds the
|
||
UI thread) and `debug_crash` (an access violation); both refuse to run in release builds.
|
||
|
||
Threading rule learned the hard way: Tauri's window getters (`hwnd()`, sizes…) called
|
||
off the UI thread wait for it to answer, so never call one while holding a lock the UI
|
||
thread might wait on, and keep window-event handlers from waiting on the player's locks
|
||
(they run on the UI thread; `lib.rs` hands resize handling to a background thread).
|
||
|
||
## App icon
|
||
|
||
`src-tauri/icons/app-icon.svg` is the source. Render it to a 1024×1024 `app-icon.png`
|
||
with a transparent background, run `npx tauri icon src-tauri/icons/app-icon.png -o <temp dir>`,
|
||
and copy back only the files already in `src-tauri/icons` (the Android and iOS sets aren't used).
|
||
|
||
## Releases
|
||
|
||
Releases are built and published locally: Windows on the Windows machine, macOS on the
|
||
Mac. CI only validates; it never builds installers on push (there are no Windows/macOS
|
||
runners). Versions follow SemVer; betas use a prerelease suffix (`0.1.0-beta.1`) and are
|
||
published as pre-releases. **Each release carries both platforms**, and the update feed
|
||
is written only once both are uploaded.
|
||
|
||
Checklist for version `X.Y.Z` (run from the repository root):
|
||
|
||
1. **Version** (either machine): set `X.Y.Z` in `package.json`, `src-tauri/Cargo.toml`
|
||
and `src-tauri/tauri.conf.json`, then `npm install --package-lock-only` to update
|
||
`package-lock.json`.
|
||
2. **Changelog**: add a `## X.Y.Z` section at the top of `CHANGELOG.md`. It becomes the
|
||
release notes and the in-app update notes.
|
||
3. **Check**: `npm run typecheck`, `npm test`, `cargo check --manifest-path src-tauri/Cargo.toml`.
|
||
4. **Commit and tag**: commit as `Release Kaleido Desktop X.Y.Z`, then
|
||
`git tag -a vX.Y.Z -m "Kaleido Desktop X.Y.Z"` and `git push origin main vX.Y.Z`
|
||
(SSH remote `origin`, already configured). Pull it on the other machine.
|
||
5. **Build and publish on Windows**: `.\scripts\build.ps1` →
|
||
`src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exe` and its `.sig`;
|
||
then `node scripts/publish-release.mjs X.Y.Z` (add `--prerelease` for betas) creates
|
||
the Forgejo release with the notes from `CHANGELOG.md` and uploads them.
|
||
6. **Build and publish on macOS**: `sh scripts/build.sh` → `bundle/dmg/Kaleido_X.Y.Z_aarch64.dmg`
|
||
(first installs) and `bundle/macos/Kaleido_X.Y.Z_aarch64.app.tar.gz` with its `.sig`
|
||
(updates); then `node scripts/publish-release.mjs X.Y.Z [--prerelease]` adds them to
|
||
the same release. The order of 5 and 6 doesn't matter.
|
||
7. **Update feed** (either machine): `node scripts/update-manifest.mjs X.Y.Z` reads the
|
||
release's assets (downloading each `.sig`) and rewrites `updates/latest.json`; commit
|
||
it (`Publish the X.Y.Z update feed`) and push. Installed copies offer the update on
|
||
their next start. The script refuses while a platform's build is missing from the
|
||
release, so neither OS is ever pointed at an older build; `--allow-missing` publishes
|
||
the feed without it (that OS then sees no update until the feed is regenerated).
|
||
8. **Verify**: download each artifact from the release and compare its SHA-256 with the
|
||
local file; `https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/raw/branch/main/updates/latest.json`
|
||
should list both platforms at the new version; CI on Actions should finish green.
|
||
|
||
Both publishing scripts read `FORGEJO_TOKEN` (repository read/write) from the
|
||
environment or the ignored `.env`, and never print it. Re-running `publish-release.mjs`
|
||
replaces that machine's assets.
|
||
|
||
**Update signing**: both build scripts sign update artifacts with the updater key from
|
||
`.tools/updater.key` (ignored; keep it safe — replacing it breaks in-app updates for
|
||
existing installs) or `TAURI_SIGNING_PRIVATE_KEY`. Both build machines need the same
|
||
key in `.tools/`; without it a build has no update archive.
|
||
|
||
**Windows** installs per user (`%LOCALAPPDATA%\Kaleido`, no admin) and is not
|
||
code-signed, so SmartScreen warns on first run. In-app updates run the installer in
|
||
passive mode and relaunch.
|
||
|
||
**macOS** builds are signed with a self-signed certificate, "Kaleido Self-Signed", in
|
||
the build Mac's login keychain (backed up, with its password, as
|
||
`.tools/macos-signing.p12` and `.tools/macos-signing.password`). A lasting signature
|
||
keeps the app's identity across updates, so the Keychain keeps trusting it with the
|
||
Plex token; ad hoc signatures change with every build and would make macOS ask again
|
||
after each update. To build on another Mac, import the backup:
|
||
`security import .tools/macos-signing.p12 -k ~/Library/Keychains/login.keychain-db -P "$(cat .tools/macos-signing.password)" -T /usr/bin/codesign`.
|
||
The app isn't notarized, so the first launch of a downloaded `.dmg` needs
|
||
System Settings → Privacy & Security → Open Anyway (or right-click → Open); in-app
|
||
updates aren't quarantined and install without that. Building runs Finder through
|
||
AppleScript to lay out the disk image window; set `CI=true` to skip that step.
|
||
|
||
Linux can be built with `sh scripts/fetch-libmpv.sh` and `npx tauri build` but isn't
|
||
published. `.forgejo/workflows/release.yml` validates every push and tag;
|
||
`.forgejo/workflows/build-installers.yml` can build installers in CI once runners exist
|
||
for each platform, and only runs when started by hand.
|