227 lines
7.9 KiB
Markdown
227 lines
7.9 KiB
Markdown
# 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)|
|