The last feature release, and the first in maintenance mode: DLSS 5 Neural Rendering, x6 / Dynamic / Custom frame generation, a Custom LUT, Qodana next to SonarCloud, the maintenance-mode policy and this week's dependency fold. CHANGELOG entry; ROADMAP release section and closing line; SECURITY supported versions 1.6.x; version references in ARCHITECTURE, TECH-SPEC (and its test count), PACKAGING, FEATURES, CONTENT-INVENTORY (+ vi), DISCLAIMER (+ vi) and the bug / accessibility forms; the six manifests 1.5.2 -> 1.6.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
527 lines
36 KiB
Markdown
527 lines
36 KiB
Markdown
# Desktop Packaging Guide
|
||
|
||
## YTDescGen — Tauri 2 Desktop and Android Apps
|
||
|
||
Reflects **v1.6.0**: Windows, macOS (Apple silicon) and Linux desktop apps plus an Android APK, all built from the same Tauri 2 project in `src-tauri/`. The web app is deployed separately — see [HOSTING.md](HOSTING.md).
|
||
|
||
---
|
||
|
||
## Why Tauri?
|
||
|
||
| Feature | Tauri 2 | Electron |
|
||
| ---------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
|
||
| Download size | 3–6 MB installers (v1.1.0: MSI 4.1 MB, NSIS 3.1 MB, `.deb` 5.3 MB); the AppImage, which bundles its libraries, 80 MB | ~150 MB |
|
||
| Memory usage | Lower — no second browser engine | Higher — bundled Chromium + Node.js |
|
||
| Bundled runtime | System WebView | Chromium |
|
||
| Backend language | Rust | Node.js |
|
||
| Security model | Capability allow-list and CSP; no Node.js in the webview | Node.js main process, Chromium renderer |
|
||
| Auto-update | Updater plugin available — not used by this app | electron-updater |
|
||
|
||
The maintainer already knew Rust from the Tauri / build-tooling ecosystem; the small binary, low memory use and simple deployment settled it.
|
||
|
||
## Prerequisites
|
||
|
||
- **Rust** (stable) via [rustup](https://rustup.rs/).
|
||
- **Node.js 26** (`.node-version`) and npm 11.
|
||
- **Tauri CLI** — the npm package `@tauri-apps/cli` is a pinned dev dependency, so `npm run tauri …` (or `npm run tauri:dev` / `npm run tauri:build`) needs nothing else. The cargo CLI (`cargo install tauri-cli --version "^2" --locked`, then `cargo tauri …`) works the same way; the Android release job uses it.
|
||
- **Platform tools**:
|
||
- Windows: Microsoft C++ Build Tools. WebView2 ships with Windows 10/11; the installers bootstrap it where it is missing (`webviewInstallMode: downloadBootstrapper`).
|
||
- macOS: Xcode Command Line Tools.
|
||
- Linux: `libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev patchelf` (what CI installs).
|
||
- **Android**: see [Android (.apk) Packaging](#android-apk-packaging).
|
||
|
||
`npm run tauri info` prints the Rust toolchain, WebView, Node and bundler versions it finds, and the bundle targets — run it first when a build fails; most "Tauri won't build" problems are a version mismatch.
|
||
|
||
`npm run check:tauri` fails when the `@tauri-apps/*` npm packages and the `tauri` crates differ in major.minor — `tauri build` refuses to run in that state, and no workflow runs `tauri build` before a release tag does.
|
||
|
||
## Project Setup
|
||
|
||
The project was initialised once with `tauri init` (not needed again). `src-tauri/` is committed, except build output (`target/`, the Gradle build folders) and the Android signing files:
|
||
|
||
```
|
||
src-tauri/
|
||
├── Cargo.toml, Cargo.lock, build.rs
|
||
├── deny.toml # cargo-deny: advisories, licences, sources
|
||
├── tauri.conf.json
|
||
├── capabilities/default.json # what the webview may call
|
||
├── installer-license.txt # Windows installers' licence page
|
||
├── icons/ # desktop + Android icons (from assets/brand/logo.svg)
|
||
├── src/
|
||
│ ├── main.rs # desktop entry → yt_desc_gen_lib::run()
|
||
│ ├── lib.rs # plugins, commands, tray, single instance
|
||
│ ├── storage.rs # backups and logs under the app data directory
|
||
│ └── file_dialog.rs # native Save / Open dialogs
|
||
└── gen/android/ # the Android Gradle project (committed)
|
||
```
|
||
|
||
The icons come from the one brand logo: `npx tauri icon assets/brand/logo.svg` regenerates them (`npm run generate:brand` does the same for the web's favicon, PWA icons and link-preview card).
|
||
|
||
### 1. tauri.conf.json
|
||
|
||
```json
|
||
{
|
||
"$schema": "https://raw.githubusercontent.com/tauri-apps/tauri/dev/crates/tauri-cli/schema.json",
|
||
"productName": "YTDescGen",
|
||
"version": "1.6.0",
|
||
"identifier": "com.skullmute.ytdescgen",
|
||
"build": {
|
||
"beforeBuildCommand": "npm run build",
|
||
"beforeDevCommand": "npm run dev",
|
||
"frontendDist": "../dist",
|
||
"devUrl": "http://localhost:5173"
|
||
},
|
||
"app": {
|
||
"windows": [
|
||
{
|
||
"title": "YTDescGen",
|
||
"width": 1280,
|
||
"height": 820,
|
||
"minWidth": 960,
|
||
"minHeight": 640,
|
||
"resizable": true,
|
||
"maximizable": true,
|
||
"fullscreen": false,
|
||
"center": true,
|
||
"zoomHotkeysEnabled": true
|
||
}
|
||
],
|
||
"security": {
|
||
"csp": "default-src 'self'; style-src 'self' 'unsafe-inline'"
|
||
}
|
||
},
|
||
"bundle": {
|
||
"active": true,
|
||
"copyright": "Copyright 2026 poli0981 (SkullMute)",
|
||
"licenseFile": "installer-license.txt",
|
||
"icon": [
|
||
"icons/32x32.png",
|
||
"icons/128x128.png",
|
||
"icons/128x128@2x.png",
|
||
"icons/icon.icns",
|
||
"icons/icon.ico"
|
||
],
|
||
"targets": "all",
|
||
"android": {
|
||
"minSdkVersion": 30
|
||
},
|
||
"macOS": {
|
||
"minimumSystemVersion": "11.0"
|
||
},
|
||
"windows": {
|
||
"webviewInstallMode": {
|
||
"type": "downloadBootstrapper"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Notes:
|
||
|
||
- The window opens at 1280×820 and can be resized down to 960×640.
|
||
- The CSP allows only the app's own files (plus inline styles, which Radix, Motion and sonner set). That is why the Vite build never inlines assets as `data:` URIs (`assetsInlineLimit: 0`) and the fonts are self-hosted. The Tauri build also carries no analytics beacon — Vite adds it only to the web build.
|
||
- There is **no `trayIcon` entry**: the tray icon is built in code (`lib.rs`), with the app icon — a `trayIcon` entry would add a second one.
|
||
- There is **no `updater` configuration** — see [Updates](#updates).
|
||
- `targets: "all"` builds every bundle the platform supports (MSI + NSIS on Windows, `.app` + `.dmg` on macOS, `.deb` + `.rpm` + AppImage on Linux); the release workflow narrows macOS to `.app`.
|
||
- `bundle.copyright` (v1.1.0) is the installers' copyright string — the Windows file properties, the macOS `Info.plist` and the Linux packages. `npm run check:copyright` (in CI) holds its year to the year of the newest commit, together with NOTICE and REUSE.toml, and `npm run update:copyright` rewrites all three: the first commit of a new year needs it.
|
||
|
||
> **Installer license page (v0.28).** The real `src-tauri/tauri.conf.json`
|
||
> sets `bundle.licenseFile: "installer-license.txt"` (path relative to
|
||
> `src-tauri/`). Tauri shows that file as an "accept the terms" page in the
|
||
> **Windows MSI/NSIS** installers. macOS `.app`/`.dmg` and the Linux packages
|
||
> have no interactive license step, so they rely on the app's first-run
|
||
> consent gate instead. If a WiX/MSI build ever rejects the `.txt`, switch to
|
||
> the per-bundler keys (`bundle.windows.wix.licenseFile` wants `.rtf`,
|
||
> `bundle.windows.nsis.licenseFile` accepts `.txt`).
|
||
|
||
### 2. Capabilities (src-tauri/capabilities/default.json)
|
||
|
||
```json
|
||
{
|
||
"identifier": "default",
|
||
"description": "Default capabilities for YTDescGen. File access goes through the app's own name-only commands and native dialogs run from Rust, so the webview gets no dialog, fs or shell permissions. set-webview-zoom backs the Ctrl/Cmd +/- zoom polyfill Tauri injects on macOS and Linux (zoomHotkeysEnabled).",
|
||
"windows": ["main"],
|
||
"permissions": ["core:default", "core:webview:allow-set-webview-zoom", "opener:default"]
|
||
}
|
||
```
|
||
|
||
`zoomHotkeysEnabled` (v1.5.1) lets the desktop app zoom with Ctrl/⌘ + = and Ctrl/⌘ + − (WebView2's own zoom control on Windows, which also takes Ctrl + mouse wheel; a polyfill on macOS and Linux that calls `set_webview_zoom`, hence the permission). Android has no zoom hotkeys; pinch zoom works there.
|
||
|
||
The webview can call Tauri's core APIs, the opener plugin (external links open in the system browser, mail client or dialler) and the app's own commands — nothing else. v1.0.0 removed the `fs` and `shell` plugins and their permissions. `tauri-plugin-dialog` is still a dependency, but only Rust uses it: the webview has no dialog permission and no dialog JavaScript package. (`tauri-plugin-fs` still appears in `Cargo.lock` as a dependency of the dialog plugin; the app does not register it.)
|
||
|
||
### 3. Rust Backend (src-tauri/src)
|
||
|
||
`main.rs` only calls `yt_desc_gen_lib::run()`. `lib.rs`, abridged:
|
||
|
||
```rust
|
||
mod file_dialog;
|
||
mod storage;
|
||
|
||
#[cfg_attr(mobile, tauri::mobile_entry_point)]
|
||
pub fn run() {
|
||
// Shared by every platform (desktop + Android). No command takes a path.
|
||
let builder = tauri::Builder::default()
|
||
.plugin(tauri_plugin_dialog::init())
|
||
.plugin(tauri_plugin_opener::init())
|
||
.invoke_handler(tauri::generate_handler![
|
||
storage::backup_list,
|
||
storage::backup_read,
|
||
storage::backup_write,
|
||
storage::backup_delete,
|
||
storage::log_append,
|
||
storage::log_list,
|
||
storage::log_read,
|
||
storage::log_delete,
|
||
storage::recover_legacy_data,
|
||
file_dialog::export_text_file,
|
||
file_dialog::import_text_file,
|
||
]);
|
||
|
||
#[cfg(desktop)]
|
||
{
|
||
// tauri_plugin_single_instance (first desktop plugin: a second launch
|
||
// focuses the running window), a tray icon built in setup() with the
|
||
// app icon and a Show / Quit menu, close-to-tray, and exit prevention
|
||
// unless Quit was chosen from the tray.
|
||
}
|
||
|
||
#[cfg(not(desktop))]
|
||
builder
|
||
.run(tauri::generate_context!())
|
||
.expect("error while building tauri application");
|
||
}
|
||
```
|
||
|
||
The commands:
|
||
|
||
| Command | Arguments | What it does |
|
||
| --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `backup_list` | — | Lists the backups in `<app data>/backups/`, newest first (`name`, `size`, `modifiedMs`) |
|
||
| `backup_read` | `name` | Reads one backup (at most 32 MB) |
|
||
| `backup_write` | `name`, `content` | Writes atomically (temporary file + rename); after writing a `ytdescgen-backup-*` file, deletes all but the newest ten of those |
|
||
| `backup_delete` | `name` | Deletes one backup (a missing file is not an error) |
|
||
| `log_append` | `name`, `content` | Appends one entry (at most 256 KB) to `<app data>/logs/<name>` |
|
||
| `log_list` | — | The log file names, sorted |
|
||
| `log_read` | `name` | Reads one log file (at most 32 MB) |
|
||
| `log_delete` | `name` | Deletes one log file |
|
||
| `recover_legacy_data` | — | Moves files written by versions before 1.0 into place (see [Legacy files](#legacy-files-from-versions-before-10)); returns `{ backups, logsMoved }` |
|
||
| `export_text_file` | `suggestedName`, `content`, `filterName`, `extensions`, `title?` | Opens the native Save dialog **in Rust** and writes the file the user picked; returns its name, or `null` when cancelled |
|
||
| `import_text_file` | `filterName`, `extensions`, `title?` | Opens the native Open dialog in Rust and returns `{ name, text }`, or `null` when cancelled |
|
||
|
||
What makes them safe:
|
||
|
||
- **Names, not paths.** `storage.rs` builds every path itself, under Tauri's `app_data_dir()`, from a name that must match `ytdescgen-<lowercase letters, digits, hyphens>.json` (at most 100 bytes) for backups or `ytdescgen-YYYYMMDD.jsonl` for logs. Anything else — `..`, separators, other extensions — is rejected before a path exists.
|
||
- **Dialogs run in Rust.** `file_dialog.rs` accepts only the extensions `json`, `jsonl`, `txt`, `csv` and `md`; reduces a suggested name to its file name (`../../x/backup.json` → `backup.json`); makes a saved file end in an allowed extension (`backup` → `backup.json`, `backup.exe` → `backup.exe.json`); and refuses imports over 20 MB or that are not UTF-8 (a byte-order mark is stripped). The chosen path never passes through JavaScript. On desktop the dialog is attached to the app window. Both commands are `async` and run the dialog and the file I/O through `tauri::async_runtime::spawn_blocking`: the dialogs' blocking API must stay off the main thread, and blocking work must not hold one of the async runtime's workers (SonarCloud `rust:S7493`).
|
||
- **Removed in v1.0.0**: the five commands that read, wrote, appended to, listed and deleted any path the webview sent (`save_to_file`, `read_from_file`, `append_to_file`, `list_dir`, `delete_file`), and the fs and shell plugins.
|
||
|
||
Both modules have unit tests (`cargo test` in `src-tauri/`): the name rules, path rejection, backup pruning, legacy recovery, dialog filters, writing the picked file and the import checks.
|
||
|
||
### 4. Frontend Tauri Integration
|
||
|
||
- **`src/utils/platform.ts`** — `IS_TAURI` (`"__TAURI_INTERNALS__" in window`), `IS_MOBILE` (an Android user agent) and `IS_MAC` (how shortcuts are spelled).
|
||
- **`src/utils/native.ts`** — the typed bridge to the commands above; `invoke` from `@tauri-apps/api/core` is imported lazily, so the web build never loads it. Exposes `appBackups` (`list`, `read`, `write`, `remove`), `appLogs` (`append`, `list`, `read`, `remove`), `recoverLegacyData`, `nativeSaveTextFile`, `nativeOpenTextFile`, and `HAS_NATIVE_DIALOGS = IS_TAURI && !IS_MOBILE`.
|
||
- **`src/utils/file-ops.ts`** — exports and imports on every platform:
|
||
|
||
```typescript
|
||
// saveTextFile({ content, filename, mimeType?, description? }) → "saved" | "cancelled" | "failed"
|
||
// 1. Tauri desktop: nativeSaveTextFile → export_text_file (dialog + write in Rust)
|
||
// 2. Web with the File System Access API (Chromium): showSaveFilePicker
|
||
// 3. Anything else (Android, Firefox, Safari): a blob download
|
||
//
|
||
// openTextFile({ extensions, description? }) → picked | cancelled | failed
|
||
// Tauri desktop: nativeOpenTextFile → import_text_file
|
||
// Elsewhere: a hidden <input type="file">; its "cancel" event reports a
|
||
// dismissed picker (no focus-timer guessing). readTextFile() applies the
|
||
// same extension and 20 MB checks to dropped files.
|
||
```
|
||
|
||
- **`src/utils/log-storage.ts`** — in Tauri, one JSONL line per log entry through `appLogs.append` into the day's file; at start-up it loads the files inside the retention window and deletes older ones. On the web it uses the `ytdescgen-logs` localStorage key instead.
|
||
- **`src/utils/open-external.ts`** — in Tauri, external links go through the opener plugin. `target="_blank"` is stripped from external anchors and clicks are intercepted in the capture phase, so a link can neither navigate the app's own webview nor trigger the webview's new-window handling (which failed on Android).
|
||
- **`src/utils/backup/startup.ts`** — `startAppData()`, run once from `App.tsx` in Tauri builds: legacy-file recovery, then automatic backups on desktop.
|
||
|
||
## Where the Apps Keep Data
|
||
|
||
- **Everything the app holds** — profiles, presets, templates, history, settings and the current draft — is in the **WebView's localStorage**, under the same `ytdescgen-*` keys as the web app (Zustand `persist`). On Windows that is WebView2's profile in `%LOCALAPPDATA%\com.skullmute.ytdescgen\EBWebView`. There is no second copy: the settings "mirror" file of earlier versions is gone.
|
||
- **Files the app writes itself** live under Tauri's `app_data_dir()` — `<data dir>/com.skullmute.ytdescgen`, which is `%APPDATA%\com.skullmute.ytdescgen` on Windows:
|
||
- `backups/` — `ytdescgen-backup-YYYYMMDD-HHmm.json` files: the automatic backups, **Back up now**, and the backup written before each restore (with a `-before-restore` suffix); the newest ten of these are kept (desktop only). Also the recovered legacy files (`ytdescgen-legacy-data*.json`), which are never deleted automatically. On desktop, Settings › Backup & restore lists them all and restores any of them.
|
||
- `logs/` — `ytdescgen-YYYYMMDD.jsonl`, one file per day, deleted after the Log retention setting (1–90 days, default 7).
|
||
- **Exports** go wherever the user picks in the Save dialog (desktop) or are downloaded (Android).
|
||
|
||
Automatic backups: 5 s after start, then after the library changes (30 s quiet, at most every 10 minutes), only when the data differs from the last backup and the library is not empty. Format and rules: [TECH-SPEC.md § 4](TECH-SPEC.md#4-backup-file-format-v100).
|
||
|
||
### Legacy files from versions before 1.0
|
||
|
||
Before v1.0.0 the frontend glued file names onto the data directory without a separator, so the settings "mirror" was written as `…\com.skullmute.ytdescgensettings.json` next to the data folder — and never read back — and the log files landed in a `…\com.skullmute.ytdescgenlogs\` folder beside it.
|
||
|
||
On start, `startAppData()` calls `recover_legacy_data`, which:
|
||
|
||
- moves the old data file (from the glued path, or `settings.json` inside the data folder) into `backups/` as `ytdescgen-legacy-data.json` (`-2`, `-3`, … when taken). It is **never applied on its own** — the data in the app is usually newer. A toast offers **Review**, which opens the restore preview for that file; on desktop it also stays listed under Settings › Backup & restore.
|
||
- merges the stray daily log files into `logs/` (appending when that day's file already exists) and removes the stray folder once it is empty; anything else in it is left alone.
|
||
|
||
The recovery runs in every Tauri build (desktop and Android); a second run finds nothing to do.
|
||
|
||
## Versioning
|
||
|
||
A release bumps the version in **six places**, and `npm run check:version` (in CI and in the release `verify` job) fails until they agree:
|
||
|
||
| File | Field |
|
||
| --------------------------- | ----------------------- |
|
||
| `package.json` | `version` |
|
||
| `package-lock.json` | `version` |
|
||
| `package-lock.json` | `packages[""].version` |
|
||
| `src-tauri/tauri.conf.json` | `version` |
|
||
| `src-tauri/Cargo.toml` | `[package] version` |
|
||
| `src-tauri/Cargo.lock` | the `yt-desc-gen` entry |
|
||
|
||
`npm version --no-git-tag-version <version>` covers the first three; the Rust / Tauri files are edited by hand (cargo also rewrites the `Cargo.lock` entry on the next non-`--locked` build or check in `src-tauri/`). Add the `CHANGELOG.md` entry in the same change.
|
||
|
||
The copyright year is not part of the version, but the first release of a new year needs `npm run update:copyright` first — `check:copyright` fails until then (see the `bundle.copyright` note above).
|
||
|
||
## Build & Release
|
||
|
||
### Development
|
||
|
||
```bash
|
||
# Web only
|
||
npm run dev
|
||
|
||
# Desktop (native window against the Vite dev server, with hot reload)
|
||
npm run tauri:dev
|
||
```
|
||
|
||
### Production Build
|
||
|
||
```bash
|
||
# Web only → dist/
|
||
npm run build
|
||
|
||
# Desktop → src-tauri/target/release/bundle/
|
||
npm run tauri:build
|
||
```
|
||
|
||
The Tauri CLI runs `npm run build` first (`beforeBuildCommand`) with `TAURI_ENV_PLATFORM` set, which switches Vite to the Tauri build: the Legal Center content only, and no static legal pages, `security.txt` or analytics beacon.
|
||
|
||
**Supported WebViews.** Since v1.3.0 both builds use Vite's default target, `baseline-widely-available` — the same engines the website supports: Chromium 111, Safari 16.4, Firefox 114 (Tauri builds were lowered to `es2020` before; the stylesheet's cascade layers already needed Chromium 99+ / Safari 15.4+, so an older WebView showed the app unstyled anyway). In practice: WebView2 on Windows (it updates itself), macOS 11 or later with current Safari updates (the app is Apple silicon only, and `bundle.macOS.minimumSystemVersion` says 11.0), WebKitGTK 2.40 or later on Linux, and on Android 11+ an Android System WebView kept current through Google Play. TypeScript keeps the app's code to the same floor: `lib` in `tsconfig.json` is ES2022, since Vite lowers syntax but never polyfills built-ins.
|
||
|
||
Output file names, with the v1.1.0 release sizes:
|
||
|
||
| Platform | Bundle | File | Size |
|
||
| --------------------- | -------------------------------- | ---------------------------------------- | ------ |
|
||
| Windows | MSI | `YTDescGen_<version>_x64_en-US.msi` | 4.1 MB |
|
||
| Windows | NSIS | `YTDescGen_<version>_x64-setup.exe` | 3.1 MB |
|
||
| macOS (Apple silicon) | `.app`, archived by tauri-action | `YTDescGen_<version>_aarch64.app.tar.gz` | 4.1 MB |
|
||
| Linux | Debian | `YTDescGen_<version>_amd64.deb` | 5.3 MB |
|
||
| Linux | RPM | `YTDescGen-<version>-1.x86_64.rpm` | 5.3 MB |
|
||
| Linux | AppImage | `YTDescGen_<version>_amd64.AppImage` | 80 MB |
|
||
| Android | Universal APK | `app-universal-release.apk` | 44 MB |
|
||
|
||
### GitHub Actions Release
|
||
|
||
Pushing a `v*` tag (signed, e.g. `v1.0.0`) runs [.github/workflows/release-desktop.yml](../.github/workflows/release-desktop.yml) and [.github/workflows/release-android.yml](../.github/workflows/release-android.yml). Both start with a **`verify`** job, and their build jobs `needs: verify`:
|
||
|
||
```yaml
|
||
- run: npm ci # a clean install: package-manager-cache: false
|
||
- run: npm run typecheck
|
||
- run: npm run test:run
|
||
- run: npm run check:version
|
||
- run: npm run check:tauri
|
||
- name: Tag matches the manifests # "v" + package.json version must equal the tag
|
||
```
|
||
|
||
Release jobs use no dependency caches — a poisoned cache entry written by another workflow must not reach the binaries — and every action is pinned by commit SHA.
|
||
|
||
The desktop build is a three-platform matrix; `tauri-apps/tauri-action` builds each target and uploads its bundles to one **draft** GitHub Release named `YTDescGen vX.Y.Z`:
|
||
|
||
| Runner | Target | Output |
|
||
| ---------------- | -------------------------- | --------------------------- |
|
||
| `windows-latest` | `x86_64-pc-windows-msvc` | `.msi`, `.exe` (NSIS) |
|
||
| `macos-15` | `aarch64-apple-darwin` | `.app.tar.gz` |
|
||
| `ubuntu-latest` | `x86_64-unknown-linux-gnu` | `.AppImage`, `.deb`, `.rpm` |
|
||
|
||
Linux runners install `libwebkit2gtk-4.1-dev`, `libgtk-3-dev`, `libayatana-appindicator3-dev`, `librsvg2-dev` and `patchelf` before building — Tauri's webview and AppImage tooling need them. AppImage bundling runs with `APPIMAGE_EXTRACT_AND_RUN=1` (linuxdeploy needs FUSE, which hosted runners don't reliably provide) and `NO_STRIP=true`.
|
||
|
||
`fail-fast: false` keeps the other platforms going if one breaks. The `bundleArgs` matrix field is concatenated with `--target ${{ matrix.target }}` and passed through to `tauri build`.
|
||
|
||
**macOS notes (v0.9.1+):**
|
||
|
||
- **DMG bundling is skipped** (`--bundles app`). Tauri's DMG bundler runs an AppleScript that flakes intermittently on hosted macOS runners (the headless display can't load Finder fast enough for `osascript` to position icons), so we ship a `.app.tar.gz` instead. Users expand the archive and drag the `.app` into `/Applications`.
|
||
- **Intel macOS (`macos-13`) is NOT built.** GitHub started deprecating the `macos-13` free runner pool in 2025; jobs queue indefinitely. If Intel support becomes a priority, switch the macos-15 entry's target to `universal-apple-darwin` (Tauri builds both archs and lipos them into one universal binary) — the runner already has the toolchain capacity.
|
||
|
||
**Code signing is intentionally skipped** for both Windows and macOS — this is an open-source personal tool, and signing certificates carry recurring cost. End users will see the standard "unverified publisher" / "unidentified developer" prompts on first launch. Document the bypass steps in the release notes if needed. (The Android APK is signed — see below.)
|
||
|
||
**Release notes.** tauri-action gives the draft a fixed body ("See the assets to download the installer for your platform."). `CHANGELOG.md` is hand-maintained and is the source for the notes; the maintainer smoke-tests the binaries and publishes the draft by hand. Publishing triggers `announce-release.yml` (the Announcements discussion and Discord).
|
||
|
||
**Manual re-run:** both workflows accept `workflow_dispatch` with a `tag` input — `gh workflow run release-desktop.yml -f tag=v1.0.0` rebuilds an existing release without deleting and recreating the tag. The manifests at that tag must already carry the version, or `verify` stops the run. Useful when a transient runner failure costs a single platform's binary.
|
||
|
||
**Backfill for pre-workflow tags:** `v0.8.0` and `v0.8.1` predate the multi-platform matrix and only have local Windows builds. To attach binaries retroactively, build manually then `gh release create v0.8.0 --notes-file CHANGELOG.md path/to/*.msi …`.
|
||
|
||
## Android (.apk) Packaging
|
||
|
||
YTDescGen also builds an installable Android APK from the **same** Tauri 2
|
||
codebase — there is no separate mobile project. Tauri 2 ships Android support;
|
||
the crate is already `cdylib`/`staticlib` with a `#[cfg_attr(mobile, …)]` entry
|
||
point, and the Android launcher icons live in `src-tauri/icons/android/`. The
|
||
desktop-only tray / single-instance / hide-to-tray logic in `src-tauri/src/lib.rs`
|
||
is gated behind `#[cfg(desktop)]` so the library compiles for Android.
|
||
|
||
### Requirements & tested versions
|
||
|
||
| | |
|
||
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| **Minimum OS** | **Android 11** (API level 30, `minSdk 30`). The APK will not install below this. |
|
||
| **Target OS** | **Android 16** (API level 36, `targetSdk 36`, `compileSdk 36`). |
|
||
| **Architectures** | Universal APK — `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`. |
|
||
| **Tested** | **Android 11 → 16.** The v0.29.0 build was verified on Android emulators across this range **and on a real device running Android 12** (the maintainer's phone). |
|
||
|
||
**No cloud backup of app data.** `AndroidManifest.xml` sets
|
||
`android:allowBackup="false"` (since v1.3.0): Android's backup to Google Drive
|
||
never copies the app's data — profiles, presets, templates, history and
|
||
settings in the WebView's `localStorage` — so it stays on the device, as the
|
||
Privacy Policy says. To move to a new phone, use **Settings › Backup &
|
||
restore**: back up to a file, then restore it on the new phone.
|
||
|
||
Where the value lives: `bundle.android.minSdkVersion` in
|
||
[`src-tauri/tauri.conf.json`](../src-tauri/tauri.conf.json) is the source of
|
||
truth used by `tauri android init`; the generated
|
||
`gen/android/app/build.gradle.kts` carries the baked `minSdk = 30` — edit that
|
||
directly if you change the floor without re-running `init`.
|
||
|
||
**Why Android 11 is the floor (rationale):**
|
||
|
||
- **Coverage.** Android 11+ accounts for the large majority of active devices in
|
||
2026 (Android 14/15 alone are the two biggest slices, and 11–13 together still
|
||
hold a sizeable share). Going lower buys few extra users at growing compat cost.
|
||
- **A modern, patched WebView.** The app renders entirely in the system WebView,
|
||
whose minimum is Android 10. On Android 11+ the WebView auto-updates via Google
|
||
Play, so the rendering/JS engine stays current and patched. This is exactly why
|
||
the **real-device test on Android 12 worked**, while a _stale_ Android-12
|
||
emulator stuck on WebView 91 showed a black screen (the `crypto.randomUUID`
|
||
boot crash) — that class of bug is fixed in v0.29.0 and is moot on an
|
||
up-to-date WebView. Since v1.3.0 the app needs a WebView at least as new as
|
||
Chromium 111, the same floor as the website, so a WebView that has never
|
||
been updated cannot run it.
|
||
- **Security upkeep.** Even though Google's _OS-level_ monthly security bulletins
|
||
for Android 11–13 have ended (Android 12 in 2025, Android 13 in early 2026),
|
||
Android 11+ keeps receiving security updates for the components that matter to a
|
||
sandboxed WebView app: Google Play system updates (Project Mainline), Google
|
||
Play services, and System WebView. Requiring strict OS-bulletin support would
|
||
mean Android 14+, which would drop more than half of users.
|
||
|
||
### Prerequisites
|
||
|
||
- **Android SDK** — platform-tools, a platform (e.g. `android-36`), build-tools. Install via Android Studio or the command-line tools.
|
||
- **Android NDK** — r27 LTS (`27.3.13750724`, what CI uses).
|
||
- **JDK 17** — Android Studio's bundled JBR works (`…/Android Studio/jbr`).
|
||
- **Rust android targets**:
|
||
```bash
|
||
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
|
||
```
|
||
|
||
Set these environment variables before any `android` command (PowerShell shown):
|
||
|
||
```powershell
|
||
$env:ANDROID_HOME = "C:\Users\<you>\AppData\Local\Android\Sdk"
|
||
$env:NDK_HOME = "C:\Users\<you>\AppData\Local\Android\Sdk\ndk\27.3.13750724"
|
||
$env:JAVA_HOME = "C:\Jetbrains\Android Studio\jbr" # or any JDK 17
|
||
```
|
||
|
||
### Initialize (one-time)
|
||
|
||
```bash
|
||
cargo tauri android init
|
||
```
|
||
|
||
Generates the Gradle project under `src-tauri/gen/android/` — **committed** to
|
||
the repo so the signing block and any manifest edits persist. It pulls launcher
|
||
icons from `src-tauri/icons/android/` and sets `applicationId =
|
||
com.skullmute.ytdescgen`. Treat `init` as a one-time step: re-running it
|
||
overwrites hand edits like the signing config below, so only re-run it if a
|
||
Tauri upgrade requires regenerating the project (then re-apply the signing edit).
|
||
|
||
### Signing (one-time)
|
||
|
||
Sideloaded APKs must be signed. Create a self-signed release keystore and keep
|
||
it **outside** the repo:
|
||
|
||
```powershell
|
||
& "$env:JAVA_HOME\bin\keytool.exe" -genkeypair -v `
|
||
-keystore C:\keys\ytdescgen-release.jks `
|
||
-keyalg RSA -keysize 2048 -validity 10000 -alias ytdescgen
|
||
```
|
||
|
||
> ⚠️ **Back this keystore up.** If you lose it you can never publish an update
|
||
> that installs over an existing copy — Android rejects a changed signature.
|
||
|
||
Create `src-tauri/gen/android/keystore.properties` (gitignored):
|
||
|
||
```properties
|
||
storeFile=C:/keys/ytdescgen-release.jks
|
||
storePassword=<store-password>
|
||
keyAlias=ytdescgen
|
||
keyPassword=<key-password>
|
||
```
|
||
|
||
`app/build.gradle.kts` carries a `release` `signingConfigs` block that reads this
|
||
file, guarded by `if (exists())` — a missing keystore yields an _unsigned_
|
||
release build rather than a hard failure (handy for contributors).
|
||
|
||
### Build
|
||
|
||
```bash
|
||
cargo tauri android build --apk
|
||
# → src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk
|
||
```
|
||
|
||
- `--apk` produces an APK. **Without it Tauri builds an `.aab`** App Bundle for the Play Store, which cannot be sideloaded.
|
||
- `cargo tauri android build --apk --target aarch64` builds an arm64-only APK (smaller download; covers virtually all modern phones).
|
||
- The build runs `npm run build` first (the `beforeBuildCommand`), then Gradle. The first build takes several minutes (Rust × up to 4 ABIs + a cold Gradle).
|
||
- For on-device iteration with hot reload: `cargo tauri android dev`.
|
||
- With the npm CLI instead of the cargo one: `npm run tauri android build -- --apk`.
|
||
|
||
Install on a device: copy the APK over (or `adb install -r <apk>`) and enable
|
||
"Install unknown apps" for the source app.
|
||
|
||
### CI
|
||
|
||
[.github/workflows/release-android.yml](../.github/workflows/release-android.yml)
|
||
runs on a `v*` tag (or `workflow_dispatch` with a `tag`). After `verify`, the
|
||
`build-android` job sets up JDK 17 (Temurin), the Android SDK, NDK
|
||
`27.3.13750724`, the four Rust Android targets and the cargo Tauri CLI; decodes
|
||
the keystore into `$RUNNER_TEMP`; writes `src-tauri/gen/android/keystore.properties`;
|
||
and runs `cargo tauri android build --apk` with `NDK_HOME` pinned to that NDK.
|
||
|
||
The APK is kept as the workflow artifact `ytdescgen-android-apk`, then attached
|
||
to the draft release with `gh release upload <tag> --clobber`. That upload needs
|
||
the draft the desktop workflow creates; if the Android job gets there first,
|
||
re-run it. It needs four repo secrets:
|
||
|
||
| Secret | Value |
|
||
| ------------------------- | --------------------------------------------------------- |
|
||
| `ANDROID_KEYSTORE_BASE64` | base64 of the `.jks` (`base64 -w0 ytdescgen-release.jks`) |
|
||
| `ANDROID_STORE_PASSWORD` | keystore store password |
|
||
| `ANDROID_KEY_PASSWORD` | key password |
|
||
| `ANDROID_KEY_ALIAS` | `ytdescgen` |
|
||
|
||
### App-level changes for Android
|
||
|
||
- **`src-tauri/src/lib.rs`** — tray / single-instance / hide-to-tray / exit-prevention are `#[cfg(desktop)]`; the dialog and opener plugins and the eleven commands are registered on every platform.
|
||
- **`src-tauri/Cargo.toml`** — `tauri-plugin-single-instance` lives in a desktop-only `[target.'cfg(not(any(target_os = "android", target_os = "ios")))'.dependencies]` table.
|
||
- **`src/utils/native.ts` / `file-ops.ts`** — `HAS_NATIVE_DIALOGS` is false on Android (a picked location there is a content URI, not a path), so exports are a WebView download and imports use the file input. Automatic backups are desktop-only; the legacy-file recovery runs on Android too.
|
||
- **Storage** — as on desktop, everything is in the WebView's localStorage; the app's own data directory holds `logs/` and, after an upgrade from an older version, the recovered legacy file in `backups/`.
|
||
|
||
## Updates
|
||
|
||
The app has no in-app updater: no updater plugin, no `updater` configuration, and it never checks for new versions. New versions are published as GitHub Releases; users download the installer or APK for their platform and install it over the existing app. User data is outside the installation — in the WebView storage and the app data directory described above — so it is kept. An Android update must be signed with the same keystore to install over an existing copy.
|
||
|
||
## Offline Capability
|
||
|
||
The desktop and Android apps work fully offline:
|
||
|
||
- All templates, configuration and translations are bundled; the non-English locales are separate chunks inside the app.
|
||
- The legal documents are rendered into the build at build time (the Legal Center reads them locally).
|
||
- Fonts (Inter, JetBrains Mono) are self-hosted.
|
||
- State lives in the WebView's localStorage; backups and logs in the app data directory.
|
||
- The app makes no network requests of its own. Only external links (opened in the system browser) need a connection.
|
||
|
||
The web app is the same code, but reaching it needs the network: the Turnstile check runs at the edge before the app loads, at most once a day per browser (see [HOSTING.md](HOSTING.md)).
|