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