Ravi/KML-Verification

Fork 0

Files

ravi ee6a3f67f7 installation guide

2026-04-27 12:55:13 +05:30

5.3 KiB

Raw Blame History

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:

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)

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)

sudo dnf install -y \
  webkit2gtk4.1-devel openssl-devel curl wget file \
  libappindicator-gtk3-devel librsvg2-devel \
  libsoup3-devel @development-tools

Linux (Arch)

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

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

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

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:

cargo check    # fast type-check
cargo build    # full debug build

TypeScript check

From kml_map_tool:

npx tsc --noEmit

4. Build a production binary

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

Login screen — create a user (any username + display name) and click Login. The username is recorded on every audit-log entry.
Import… → pick Fixed assets (JSON) and point at one of the sample files in the repo (e.g. Double_Arm_Street_Light_mcw.json).
The map auto-centers on the first imported asset; pan / zoom to explore.
See 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.

5.3 KiB Raw Blame History Unescape Escape