# Installation & Run

Tauri 2 desktop app. The frontend is React 19 + Vite + TypeScript; the backend is Rust + SQLite via sqlx.

---

## 1. Prerequisites

### Common (all platforms)
- **Node.js ≥ 18** and **npm** (or pnpm / yarn — the lockfile is `package-lock.json`).
- **Rust** stable, installed via [rustup](https://rustup.rs/):
  ```bash
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  source "$HOME/.cargo/env"
  ```
- **Tauri CLI** (project-local; no global install needed — `npm install` pulls `@tauri-apps/cli`).

### Linux (Debian / Ubuntu / Pop!_OS)
```bash
sudo apt update
sudo apt install -y \
  build-essential curl wget file \
  libwebkit2gtk-4.1-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  libsoup-3.0-dev \
  pkg-config
```
On Ubuntu 22.04 / 24.04 the `4.1` WebKitGTK packages are correct for Tauri 2. If `apt` complains, also try `libjavascriptcoregtk-4.1-dev`.

### Linux (Fedora / RHEL)
```bash
sudo dnf install -y \
  webkit2gtk4.1-devel openssl-devel curl wget file \
  libappindicator-gtk3-devel librsvg2-devel \
  libsoup3-devel @development-tools
```

### Linux (Arch)
```bash
sudo pacman -S --needed \
  webkit2gtk-4.1 base-devel curl wget file \
  openssl appmenu-gtk-module libayatana-appindicator \
  librsvg libsoup3
```

### macOS
- **Xcode Command Line Tools**:
  ```bash
  xcode-select --install
  ```
- That's it — Apple ships everything else (WebKit, Core Foundation, etc.).

### Windows
- **Microsoft C++ Build Tools** (Visual Studio Installer → "Desktop development with C++").
- **WebView2 runtime** — pre-installed on Windows 11 / recent Win10. Otherwise grab it from <https://developer.microsoft.com/microsoft-edge/webview2/>.

---

## 2. Clone and install

```bash
git clone <your-repo-url> KML_Tool
cd KML_Tool/kml_map_tool
npm install
```

`npm install` also fetches `@tauri-apps/cli`. Rust dependencies build on the first `tauri dev` / `tauri build`.

---

## 3. Run in development mode

```bash
npm run tauri dev
```

What this does:
- Starts Vite on `http://localhost:1420` (HMR for React).
- Compiles the Rust backend (`cargo build` — first run takes 5–10 min as sqlx, geo, kml, deck.gl deps cache).
- Launches the desktop window. Closing the window stops both processes.

**First-run database** — the app creates `markers.db` inside the OS app-data directory:
- Linux: `~/.local/share/com.kml_map_tool.app/markers.db` (or similar — varies by distro / Tauri identifier).
- macOS: `~/Library/Application Support/com.kml_map_tool.app/markers.db`
- Windows: `%APPDATA%\com.kml_map_tool.app\markers.db`

You'll see migrations run silently in the logs. To wipe the DB and start over, use **Reset DB** in the Data section of the app, or delete the file.

### Useful scripts
```bash
npm run dev         # frontend only (Vite, no Tauri window) — for browser-only UI testing
npm run build       # type-check + production frontend build (output: dist/)
npm run preview     # preview the production frontend (no Tauri)
npm run tauri dev   # full Tauri dev (frontend + Rust backend + desktop window)
```

### Rust-only compile check
From `kml_map_tool/src-tauri`:
```bash
cargo check    # fast type-check
cargo build    # full debug build
```

### TypeScript check
From `kml_map_tool`:
```bash
npx tsc --noEmit
```

---

## 4. Build a production binary

```bash
npm run tauri build
```

Outputs to `src-tauri/target/release/bundle/`:

- **Linux**: `*.AppImage`, `*.deb`, `*.rpm` (depending on installed packagers; `appimagetool` and `dpkg-deb` need to be on `$PATH` for the corresponding bundle to be produced).
- **macOS**: `*.app` and `*.dmg`. For a signed/notarised build, set `APPLE_*` env vars per the Tauri docs.
- **Windows**: `*.msi` (WiX) and `*.exe` (NSIS).

Single-arch native build only — cross-compiling Tauri apps (e.g. macOS → Linux) is not supported out of the box.

---

## 5. First steps after launch

1. **Login screen** — create a user (any username + display name) and click Login. The username is recorded on every audit-log entry.
2. **Import…** → pick `Fixed assets (JSON)` and point at one of the sample files in the repo (e.g. `Double_Arm_Street_Light_mcw.json`).
3. The map auto-centers on the first imported asset; pan / zoom to explore.
4. See [README.md](./README.md) for the full feature tour.

---

## 6. Troubleshooting

### `error: linker 'cc' not found` (Linux)
`build-essential` (Debian/Ubuntu) or the equivalent dev tools group is missing. See prerequisites above.

### `failed to find webkit2gtk-4.1` (Linux)
The dev package is missing. On Ubuntu < 22.04 you may have only `4.0` available — Tauri 2 requires `4.1`. Upgrade or build WebKitGTK from source.

### `WebView2 runtime not found` (Windows)
Install from <https://developer.microsoft.com/microsoft-edge/webview2/>.

### Rust build is incredibly slow / OOM
The first build pulls hundreds of crates. Add `RUSTFLAGS="-C codegen-units=16"` and use a release machine with ≥ 8 GB RAM. Subsequent builds are incremental and fast.

### `g_object_unref: assertion 'G_IS_OBJECT (object)' failed` on shutdown (Linux)
Harmless — upstream WebKitGTK / libsoup ref-counting noise. Ignore.

### "Database is locked" errors during heavy bulk operations
sqlx pool size is 4. If you hit contention, increase `max_connections` in `src-tauri/src/db.rs` and rebuild.

### App window blank / white on Wayland
Try `WEBKIT_DISABLE_COMPOSITING_MODE=1 npm run tauri dev`.