diff --git a/INSTALLATION.md b/INSTALLATION.md index df0360e..aabd3d4 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,160 +1,84 @@ -# Installation & Run +# Installation & Run (Linux) -Tauri 2 desktop app. The frontend is React 19 + Vite + TypeScript; the backend is Rust + SQLite via sqlx. +Tauri 2 + React + Vite + Rust + SQLite. Tested on Ubuntu 22.04+ and Pop!_OS. --- ## 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`). +### Node.js 20 (or any LTS ≥ 18) +The Tauri 2 CLI uses optional chaining and crashes with `SyntaxError: Unexpected token '.'` on Node 14 or older. Check with `node -v`. -### Linux (Debian / Ubuntu / Pop!_OS) +```bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash +exec $SHELL +nvm install 20 +nvm alias default 20 +``` + +### Rust (stable) +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +source "$HOME/.cargo/env" +``` + +### System libraries (Debian / Ubuntu / Pop!_OS) ```bash sudo apt update sudo apt install -y \ - build-essential curl wget file \ + build-essential curl wget file pkg-config \ libwebkit2gtk-4.1-dev \ libssl-dev \ libayatana-appindicator3-dev \ librsvg2-dev \ - libsoup-3.0-dev \ - pkg-config + libsoup-3.0-dev ``` -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 . --- -## 2. Clone and install +## 2. Install dependencies ```bash -git clone KML_Tool -cd KML_Tool/kml_map_tool +cd kml_map_tool npm install ``` -`npm install` also fetches `@tauri-apps/cli`. Rust dependencies build on the first `tauri dev` / `tauri build`. +This also pulls `@tauri-apps/cli`. Rust deps build on first run. --- -## 3. Run in development mode +## 3. Run in development ```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: 5–10 min while Rust deps compile. +- Subsequent runs: seconds. +- Closing the window stops everything. -**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 -``` +The SQLite database is created at `~/.local/share/com.kml_map_tool.app/markers.db` on first launch. To wipe it, use **Reset DB** in the app or delete the file. --- -## 4. Build a production binary +## 4. Build a release 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. +Output: `src-tauri/target/release/bundle/` — `.AppImage`, `.deb`, and `.rpm` (whichever packagers are present on `$PATH`). --- -## 5. First steps after launch +## 5. Troubleshooting -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. +| Symptom | Fix | +|---|---| +| `SyntaxError: Unexpected token '.'` from `tauri.js` | Node too old. Upgrade to ≥ 18, then `rm -rf node_modules package-lock.json && npm install`. | +| `error: linker 'cc' not found` | `sudo apt install build-essential` | +| `failed to find webkit2gtk-4.1` | Install `libwebkit2gtk-4.1-dev`. On Ubuntu < 22.04 only `4.0` is available — upgrade Ubuntu. | +| Blank white window on Wayland | `WEBKIT_DISABLE_COMPOSITING_MODE=1 npm run tauri dev` | +| `g_object_unref: assertion 'G_IS_OBJECT (object)' failed` on quit | Harmless WebKitGTK noise. Ignore. | ---- - -## 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 . - -### 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`. +See [README.md](./README.md) for the user guide.