161 lines
5.3 KiB
Markdown
161 lines
5.3 KiB
Markdown
# 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`.
|