SR-Label-SamTool/sam-tool-tauri/docs/BUILD_RELEASE.md

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

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:

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

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

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:

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:

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 → "version": "...". Bump it before each release; the value is baked into both the binary and the installer filenames.

---

Smoke-test the release build locally

# 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:

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:

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)