first version
This commit is contained in:
226
docs/BUILD_RELEASE.md
Normal file
226
docs/BUILD_RELEASE.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Building the Tauri app for release (instead of `dev` mode)
|
||||
|
||||
Day-to-day you've been running the desktop app via `npm run tauri dev` —
|
||||
that's the dev server: hot-reload, attached browser devtools, slower
|
||||
binary, and it stays bound to your terminal. For real use (or shipping to
|
||||
another machine), you build a standalone executable + installer.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
```bash
|
||||
cd sam-tool-tauri
|
||||
npm install # only on first run / after pulling deps
|
||||
npm run tauri build # produces a release binary + installer
|
||||
```
|
||||
|
||||
Output lands under
|
||||
`sam-tool-tauri/src-tauri/target/release/bundle/`. On Linux you'll find:
|
||||
|
||||
- `bundle/deb/sam-tool-tauri_<version>_amd64.deb` — installable on
|
||||
Debian/Ubuntu hosts (`sudo dpkg -i …`).
|
||||
- `bundle/appimage/sam-tool-tauri_<version>_amd64.AppImage` — single
|
||||
portable file, `chmod +x` and run.
|
||||
- `bundle/rpm/…` if rpm tooling is present.
|
||||
|
||||
Plus the raw binary at
|
||||
`src-tauri/target/release/sam-tool-tauri` (no installer, just `./run` it).
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites (Linux)
|
||||
|
||||
If you've only ever run `tauri dev`, you might be missing the system
|
||||
libraries the bundler needs. On Ubuntu / Debian / Pop!_OS:
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y \
|
||||
libwebkit2gtk-4.1-dev \
|
||||
libgtk-3-dev \
|
||||
libayatana-appindicator3-dev \
|
||||
librsvg2-dev \
|
||||
patchelf \
|
||||
build-essential \
|
||||
curl wget file \
|
||||
libssl-dev pkg-config
|
||||
```
|
||||
|
||||
You also need a recent Rust toolchain (Tauri 2 requires `rustc >= 1.77`):
|
||||
|
||||
```bash
|
||||
rustup update stable
|
||||
rustc --version # confirm >= 1.77
|
||||
```
|
||||
|
||||
For AppImage bundling specifically, the Tauri CLI auto-fetches the
|
||||
AppImage tools on first build. The first run will be slower; subsequent
|
||||
builds reuse the cache.
|
||||
|
||||
---
|
||||
|
||||
## Build profiles
|
||||
|
||||
Two ways to produce a release binary, with different tradeoffs:
|
||||
|
||||
### A. `npm run tauri build` — full installer build
|
||||
|
||||
```bash
|
||||
npm run tauri build
|
||||
```
|
||||
|
||||
What it does:
|
||||
1. Runs `vite build` → produces optimized JS/CSS in `dist/`.
|
||||
2. Compiles `src-tauri/` Rust crate in `--release` mode.
|
||||
3. Bundles everything into platform-native installers under
|
||||
`bundle/`.
|
||||
|
||||
Pros: production-grade, optimised, signable, distributable.
|
||||
Cons: slow first time (Rust release builds + bundler downloads).
|
||||
|
||||
### B. `cargo build --release` — binary only, skip installers
|
||||
|
||||
If you only want the executable (e.g. for quick testing on a sibling
|
||||
machine on the same OS), drop the bundling step:
|
||||
|
||||
```bash
|
||||
cd sam-tool-tauri
|
||||
npm run build # bundles the frontend → dist/
|
||||
cd src-tauri
|
||||
cargo build --release # binary at target/release/sam-tool-tauri
|
||||
```
|
||||
|
||||
The resulting binary expects `dist/` from the same checkout to be
|
||||
present (Tauri 2 embeds frontend assets, so once compiled it's
|
||||
self-contained). Faster than the full bundle, but no `.deb`/`.AppImage`.
|
||||
|
||||
### C. Debug build — fast compile, big binary
|
||||
|
||||
For iterating on Rust changes without a full release re-compile:
|
||||
|
||||
```bash
|
||||
cd src-tauri
|
||||
cargo build # debug profile — fast compile, big slow binary
|
||||
./target/debug/sam-tool-tauri
|
||||
```
|
||||
|
||||
This is essentially what `tauri dev` runs under the hood, minus the dev
|
||||
server.
|
||||
|
||||
---
|
||||
|
||||
## Where the artefacts go
|
||||
|
||||
```
|
||||
sam-tool-tauri/
|
||||
├── dist/ ← bundled frontend (vite build)
|
||||
└── src-tauri/target/
|
||||
├── debug/sam-tool-tauri ← debug binary
|
||||
└── release/
|
||||
├── sam-tool-tauri ← optimised binary
|
||||
└── bundle/
|
||||
├── deb/sam-tool-tauri_<v>_amd64.deb
|
||||
├── appimage/sam-tool-tauri_<v>_amd64.AppImage
|
||||
└── rpm/… (if `rpm` tools are installed)
|
||||
```
|
||||
|
||||
`bundle/deb/` and `bundle/appimage/` are the things you'd ship to other
|
||||
machines.
|
||||
|
||||
---
|
||||
|
||||
## Versioning
|
||||
|
||||
The version string comes from
|
||||
[`src-tauri/tauri.conf.json`](../sam-tool-tauri/src-tauri/tauri.conf.json) →
|
||||
`"version": "..."`. Bump it before each release; the value is baked
|
||||
into both the binary and the installer filenames.
|
||||
|
||||
---
|
||||
|
||||
## Smoke-test the release build locally
|
||||
|
||||
```bash
|
||||
# Run the binary directly:
|
||||
./src-tauri/target/release/sam-tool-tauri
|
||||
|
||||
# Or install the .deb and launch from your app menu:
|
||||
sudo dpkg -i src-tauri/target/release/bundle/deb/sam-tool-tauri_*_amd64.deb
|
||||
sam-tool-tauri # binary on $PATH after dpkg
|
||||
|
||||
# Or run the AppImage portably:
|
||||
chmod +x src-tauri/target/release/bundle/appimage/sam-tool-tauri_*.AppImage
|
||||
./src-tauri/target/release/bundle/appimage/sam-tool-tauri_*.AppImage
|
||||
```
|
||||
|
||||
The release build behaves exactly like `dev` (same UI, same SAM
|
||||
integration), with these differences:
|
||||
|
||||
- No devtools by default. To re-enable in a release build, edit
|
||||
`src-tauri/tauri.conf.json` → `"app.windows[0].devtools": true`,
|
||||
rebuild.
|
||||
- Faster cold start, smaller memory footprint, optimised JS bundle.
|
||||
- React `StrictMode` still doubles state-updaters in dev — but that's a
|
||||
React-side flag, not Tauri's. The stripped-down behaviour comes from
|
||||
Vite's production mode (`process.env.NODE_ENV === 'production'`).
|
||||
|
||||
---
|
||||
|
||||
## Distributing to another PC
|
||||
|
||||
The user only needs **one** of the bundles:
|
||||
|
||||
**Debian/Ubuntu:**
|
||||
```bash
|
||||
scp src-tauri/target/release/bundle/deb/sam-tool-tauri_*_amd64.deb \
|
||||
target-host:/tmp/
|
||||
ssh target-host "sudo dpkg -i /tmp/sam-tool-tauri_*_amd64.deb"
|
||||
```
|
||||
|
||||
**Anywhere with glibc:**
|
||||
```bash
|
||||
scp src-tauri/target/release/bundle/appimage/sam-tool-tauri_*.AppImage \
|
||||
target-host:/home/user/
|
||||
ssh target-host "chmod +x ~/sam-tool-tauri_*.AppImage && ~/sam-tool-tauri_*.AppImage"
|
||||
```
|
||||
|
||||
The target host needs `webkit2gtk` runtime (most desktops already have
|
||||
it) and `ffmpeg` if they want the Extract mode to decode video. The
|
||||
sibling SAM2 backend and weights are *not* bundled into the desktop app —
|
||||
those live separately and are reached over HTTP, configurable from
|
||||
**Settings → SAM backend URL**.
|
||||
|
||||
---
|
||||
|
||||
## Common build errors
|
||||
|
||||
| Error | Fix |
|
||||
|--------------------------------------------------------------|-------------------------------------------------------------------------------------------|
|
||||
| `error: linker 'cc' not found` | `sudo apt install build-essential` |
|
||||
| `failed to find webkit2gtk-4.1` / `gobject-introspection` | `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev` (see prerequisites) |
|
||||
| `failed to bundle .deb` | Missing `dpkg-deb`. `sudo apt install dpkg` |
|
||||
| AppImage step hangs on first build | Tauri downloading appimagetool; wait or pre-fetch under `~/.cache/tauri/` |
|
||||
| `Could not resolve "@tauri-apps/api"` | `npm install` again in `sam-tool-tauri/` |
|
||||
| Build OK on dev machine, fails on Ubuntu 22.04 | webkit2gtk-4.0 vs 4.1 mismatch — Tauri 2 needs 4.1; older Ubuntus may need a backport PPA |
|
||||
|
||||
---
|
||||
|
||||
## Cross-compilation (Windows / macOS targets)
|
||||
|
||||
Out of scope for this repo (Linux-only per CLAUDE.md), but for
|
||||
completeness — Tauri supports it via extra rust targets and a Windows or
|
||||
macOS host machine. See the upstream Tauri docs:
|
||||
https://tauri.app/distribute/
|
||||
|
||||
---
|
||||
|
||||
## Recap — when to run what
|
||||
|
||||
| You want to… | Command |
|
||||
|---------------------------------------------|-------------------------------------------------|
|
||||
| Iterate on UI (hot reload) | `npm run tauri dev` |
|
||||
| Iterate on Rust quickly | `cd src-tauri && cargo build && ./target/debug/sam-tool-tauri` |
|
||||
| Make a release executable, no installer | `npm run build && cd src-tauri && cargo build --release` |
|
||||
| Make installers (.deb / AppImage) | `npm run tauri build` |
|
||||
| Inspect production frontend without Tauri | `npm run preview` (browser-only, no native APIs)|
|
||||
Reference in New Issue
Block a user