From 716fdf5bac5372c62cccc3df1fcba2f4c1d39864 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Tejero=20Cantero?= Date: Tue, 14 Jul 2026 14:51:19 +0200 Subject: [PATCH 1/5] Make npm run setup provision everything the build needs Previously scripts/download-liblbug.sh ran with its default target (repo lib/), which neither build.rs, .cargo/config.toml, nor the macOS staging script read, and the sigma.js fork referenced by package.json (file:.deps/sigma.js/packages/sigma) was only provisioned in CI. scripts/setup.sh now clones and builds the sigma fork (same repo/ref as .github/workflows/build.yml), downloads prebuilt liblbug into src-tauri/liblbug at the exact version pinned by the lbug crate in src-tauri/Cargo.toml (re-downloading when the pin changes), downloads icebug, and stages macOS frameworks. Co-Authored-By: Claude Fable 5 --- package.json | 2 +- scripts/setup.sh | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) create mode 100755 scripts/setup.sh diff --git a/package.json b/package.json index 07662ae..728877c 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "version": "0.15.1", "type": "module", "scripts": { - "setup": "bash scripts/download-liblbug.sh && bash scripts/download_icebug.sh && bash scripts/stage_macos_frameworks.sh", + "setup": "bash scripts/setup.sh", "dev:frontend": "vite", "build:frontend": "tsc -b && vite build", "tauri": "cargo tauri", diff --git a/scripts/setup.sh b/scripts/setup.sh new file mode 100755 index 0000000..594d712 --- /dev/null +++ b/scripts/setup.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# One-shot setup: download the prebuilt native libraries into src-tauri/. +# The liblbug version is pinned to the lbug crate version in src-tauri/Cargo.toml. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +LIBLBUG_DIR="$PROJECT_DIR/src-tauri/liblbug" +SIGMA_DIR="$PROJECT_DIR/.deps/sigma.js" +SIGMA_REPO="${SIGMA_REPO:-https://github.com/adsharma/sigma.js}" +SIGMA_REF="${SIGMA_REF:-icebug-arrow-graph}" + +# Vendored sigma.js fork (same source as .github/workflows/build.yml). +if [ ! -f "$SIGMA_DIR/package.json" ]; then + rm -rf "$SIGMA_DIR" + git clone --branch "$SIGMA_REF" --depth 1 "$SIGMA_REPO" "$SIGMA_DIR" +fi +if [ ! -d "$SIGMA_DIR/packages/sigma/dist" ]; then + npm ci --prefix "$SIGMA_DIR" + npm run build --prefix "$SIGMA_DIR" +fi + +LBUG_VERSION="$(sed -n 's/^lbug = { version = "\([^"]*\)".*/\1/p' "$PROJECT_DIR/src-tauri/Cargo.toml")" +if [ -z "$LBUG_VERSION" ]; then + echo "Could not read the lbug version from src-tauri/Cargo.toml" >&2 + exit 1 +fi + +# Wipe a cached prebuilt that does not match the pinned version. +if [ -d "$LIBLBUG_DIR" ] && [ "$(cat "$LIBLBUG_DIR/.version" 2>/dev/null)" != "$LBUG_VERSION" ]; then + echo "Cached liblbug does not match pinned version $LBUG_VERSION, re-downloading" + rm -rf "$LIBLBUG_DIR" +fi + +LBUG_TARGET_DIR="$LIBLBUG_DIR" LBUG_LIB_KIND="${LBUG_LIB_KIND:-shared}" LBUG_VERSION="$LBUG_VERSION" \ + bash "$SCRIPT_DIR/download-liblbug.sh" +echo "$LBUG_VERSION" > "$LIBLBUG_DIR/.version" + +bash "$SCRIPT_DIR/download_icebug.sh" +bash "$SCRIPT_DIR/stage_macos_frameworks.sh" From 00a0b1a1ff07d73a15ebbf7507ea0609904eaa8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Tejero=20Cantero?= Date: Tue, 14 Jul 2026 14:51:48 +0200 Subject: [PATCH 2/5] README: document how to actually build bugscope The previous instructions (npm install, cargo tauri dev) omitted every non-obvious prerequisite: the Tauri CLI cargo plugin, the Tauri system libraries, the vendored sigma.js fork, the prebuilt liblbug/icebug libraries, and Apache Arrow C++ / OpenMP for the icebug-analytics feature. They also required a "ladybugdb backend API at :3001" that nothing in the code references. Replace them with a platform-agnostic build overview, a Debian 13 walkthrough verified end to end on trixie, and a troubleshooting section for the failure modes met along the way. Notably, the Arrow C++ major version must match the one the icebug prebuilt was linked against (currently 24), so the walkthrough pins and holds libarrow-dev. Co-Authored-By: Claude Fable 5 --- README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 91f01a8..66cc8a9 100644 --- a/README.md +++ b/README.md @@ -15,19 +15,65 @@ An interactive graph visualization tool for ladybugdb. Explore relationships bet - **Relationship Labels** - Hover over edges to see the type of relationship between connected nodes. - **Optional LLM Cluster Names** - Provide an LLM access token to name Leiden clusters from a random sample of 15 node labels in each cluster. -## Getting Started +## Building -1. **Install dependencies** - ```bash - npm install - ``` +Bugscope is a [Tauri 2](https://v2.tauri.app) desktop app: a React/Vite frontend plus a Rust backend that links two prebuilt native libraries. What you need, on any platform: -2. **Start the application** +1. **Node.js ≥ 22 and npm** - frontend tooling (Vite 7). +2. **Rust toolchain** ([rustup](https://rustup.rs)) **and the Tauri CLI**: `cargo install tauri-cli --version "^2"`. The CLI is a separate cargo subcommand; without it `cargo tauri` fails with `no such command: tauri`. +3. **Tauri system libraries** - on Linux: WebKitGTK 4.1, GTK 3, libsoup 3, and Pango development packages; see the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) for your distribution. On macOS: Xcode command line tools. +4. **JS dependencies**: `npm install`. +5. **Vendored and prebuilt dependencies**: `npm run setup` provisions all of: + - the **sigma.js fork** with the `sigma/icebug` entry point, cloned from [adsharma/sigma.js](https://github.com/adsharma/sigma.js) (`icebug-arrow-graph` branch) into `.deps/sigma.js/` and built there (`package.json` references it as `file:.deps/sigma.js/packages/sigma`); + - **liblbug** (LadybugDB C API) into `src-tauri/liblbug/`, at the version pinned by the `lbug` crate in `src-tauri/Cargo.toml`; + - **icebug** (NetworKit-based graph analytics) into `src-tauri/icebug/` - only linked when building with `--features=icebug-analytics`. +6. **Apache Arrow C++ and OpenMP** (only for `--features=icebug-analytics`) - the icebug build script locates Arrow with `pkg-config arrow`, so the Arrow development package must be installed system-wide, and the icebug prebuilt additionally needs the LLVM OpenMP runtime (`libomp.so.5`). The Arrow **major version must match** the one the icebug prebuilt was linked against; check it with `objdump -p src-tauri/icebug/lib/libnetworkit.so | grep NEEDED` (currently `libarrow.so.2400`, i.e. Arrow 24). On macOS: `brew install apache-arrow libomp`. +7. **Run**: ```bash - cargo tauri dev --features=icebug-analytics -- -- ../test.lbdb + cargo tauri dev # without analytics (no Arrow needed) + cargo tauri dev --features=icebug-analytics # with Leiden clustering etc. ``` + Append `-- -- /path/to/database.lbdb` to load a database at startup (the extra `--` separates tauri args from cargo args from app args). + +### Debian 13 (trixie) + +Verified end to end on a stock trixie installation: + +```bash +# 1. Tauri system libraries and build tools +sudo apt install libgtk-3-dev libsoup-3.0-dev libwebkit2gtk-4.1-dev \ + libjavascriptcoregtk-4.1-dev libpango1.0-dev pkg-config \ + wget ca-certificates lsb-release + +# 2. Rust toolchain via rustup, then the Tauri CLI +cargo install tauri-cli --version "^2" + +# 3. Apache Arrow apt repository (Debian ships no libarrow packages) +wget https://packages.apache.org/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb +sudo apt install -y -V ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb +sudo apt update -The application opens as a Tauri desktop app. Pass a `.lbdb` path after `-- --` to load that database at startup. +# 4. Arrow C++ pinned to the major version the icebug prebuilt links (currently 24), +# plus the LLVM OpenMP runtime needed by the icebug prebuilt +sudo apt install libarrow-dev=24.0.0-1 libarrow2400 libomp5-19 +sudo apt-mark hold libarrow-dev # keep apt upgrade from moving to a mismatched major + +# 5. Dependencies and prebuilt libraries +npm install +npm run setup + +# 6. Run +cargo tauri dev --features=icebug-analytics +``` + +### Troubleshooting + +- `error: no such command: tauri` - the Tauri CLI is not installed: `cargo install tauri-cli --version "^2"`. +- `Failed to resolve import "sigma"` in the app window - the vendored sigma.js fork in `.deps/sigma.js` is missing or unbuilt; run `npm run setup`. +- `The system library arrow required by crate icebug was not found` - `libarrow-dev` is missing (steps 3-4 above), or you are building with `--features=icebug-analytics` unintentionally; plain `cargo tauri dev` does not need Arrow. +- `error while loading shared libraries: libarrow.so.NN00` - the installed Arrow major version differs from the one the icebug prebuilt was linked against. Install the matching runtime and dev packages (e.g. `libarrow2400` + `libarrow-dev=24.0.0-1`), then `cargo clean -p icebug` and rebuild. +- `error while loading shared libraries: libomp.so.5` - LLVM OpenMP runtime missing: `sudo apt install libomp5-19` (Debian/Ubuntu), `brew install libomp` (macOS). +- Prebuilt liblbug and the `lbug` crate version in `src-tauri/Cargo.toml` must match; `npm run setup` re-downloads automatically when the pin changes. ## Usage @@ -44,8 +90,3 @@ The application opens as a Tauri desktop app. Pass a `.lbdb` path after `-- --` Cluster naming is disabled by default. To enable it, expand the sidebar's Cluster Names section, enter an LLM access token, and click Apply. Cluster computation still starts with local fallback names; the backend only sends a random sample of 15 labels for clusters that are currently visible in the drill view, then falls back to `Cluster N` if a request fails. The endpoint defaults to `https://openrouter.ai`, and the model field defaults to `deepseek-v4-flash`. Base endpoints are sent through their `/api/v1/chat/completions` path, and both fields can be changed in the sidebar before applying. - -## Requirements - -- Node.js -- A running ladybugdb backend API at `http://localhost:3001` From 49656cbea81773fccd0eeb307b4fad139a9aa1e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Tejero=20Cantero?= Date: Tue, 14 Jul 2026 14:52:10 +0200 Subject: [PATCH 3/5] README: note Ubuntu 26.04 applicability (untested) Package names match Debian's and the Apache Arrow repository serves ubuntu/resolute with libarrow-dev, so the Debian 13 steps should apply verbatim. Not verified end to end. Co-Authored-By: Claude Fable 5 --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 66cc8a9..55f57d2 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,10 @@ npm run setup cargo tauri dev --features=icebug-analytics ``` +### Ubuntu 26.04 (resolute) + +The same steps should work unchanged: the package names match and the Arrow repository serves `ubuntu/resolute` (verified to contain `libarrow-dev`). Not yet tested end to end - please report findings. + ### Troubleshooting - `error: no such command: tauri` - the Tauri CLI is not installed: `cargo install tauri-cli --version "^2"`. From f9affd61e614224d489508efa7349650e1bee2f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Tejero=20Cantero?= Date: Tue, 14 Jul 2026 14:52:32 +0200 Subject: [PATCH 4/5] README: troubleshoot libarrow-dev vs trixie-backports curl conflict Situational: only hits Debian 13 systems that have pulled the curl stack from trixie-backports (libcurl3t64-gnutls 8.20 and friends). libarrow-dev needs the stable libcurl4-openssl-dev chain, whose libnghttp3-dev conflicts with the backports libnghttp3-9; apt cannot resolve it unless the whole cluster is downgraded in one transaction. The pinned version strings will age with trixie point releases. Co-Authored-By: Claude Fable 5 --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 55f57d2..84f148b 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,13 @@ The same steps should work unchanged: the package names match and the Arrow repo - `The system library arrow required by crate icebug was not found` - `libarrow-dev` is missing (steps 3-4 above), or you are building with `--features=icebug-analytics` unintentionally; plain `cargo tauri dev` does not need Arrow. - `error while loading shared libraries: libarrow.so.NN00` - the installed Arrow major version differs from the one the icebug prebuilt was linked against. Install the matching runtime and dev packages (e.g. `libarrow2400` + `libarrow-dev=24.0.0-1`), then `cargo clean -p icebug` and rebuild. - `error while loading shared libraries: libomp.so.5` - LLVM OpenMP runtime missing: `sudo apt install libomp5-19` (Debian/Ubuntu), `brew install libomp` (macOS). +- Debian: installing `libarrow-dev` fails with `libnghttp3-dev : Depends: libnghttp3-9 (= 1.8.0-1)` or similar - you have curl libraries from trixie-backports; `libarrow-dev` needs the stable `libcurl4-openssl-dev` chain. Downgrade the whole cluster in one transaction: + ```bash + sudo apt install --allow-downgrades \ + libcurl3t64-gnutls=8.14.1-2+deb13u4 libcurl4-gnutls- \ + libnghttp3-9=1.8.0-1 \ + libngtcp2-16=1.11.0-1+deb13u1 libngtcp2-crypto-gnutls8=1.11.0-1+deb13u1 + ``` - Prebuilt liblbug and the `lbug` crate version in `src-tauri/Cargo.toml` must match; `npm run setup` re-downloads automatically when the pin changes. ## Usage From 4df0a0d8826c5cb64d53cd6d72c7f87a67ca0a63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Tejero=20Cantero?= Date: Tue, 14 Jul 2026 14:52:32 +0200 Subject: [PATCH 5/5] Update lbug to 0.18.1 0.18.1 fixes SSL CA certificate detection for extension downloads (LadybugDB/ladybug#640). Caveat: SSL on macOS is not fully settled in this release; the published 0.18.1 macOS Node addon still hardcodes build-machine OpenSSL paths, addressed post-release by LadybugDB/ladybug#682. That addon is a different artifact from the liblbug C library linked here, so it does not gate this bump. Point CI's liblbug artifact resolution at the matching ref; CI needs a successful build-and-deploy run for v0.18.1 to exist. Co-Authored-By: Claude Fable 5 --- .github/workflows/build.yml | 2 +- src-tauri/Cargo.lock | 4 ++-- src-tauri/Cargo.toml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c35f355..fa32e9a 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -70,7 +70,7 @@ jobs: uses: actions/checkout@v4 with: repository: LadybugDB/ladybug - ref: 'v0.17.0' + ref: 'v0.18.1' path: ladybug - name: Checkout Sigma diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock index c863ca8..f051566 100644 --- a/src-tauri/Cargo.lock +++ b/src-tauri/Cargo.lock @@ -2201,9 +2201,9 @@ dependencies = [ [[package]] name = "lbug" -version = "0.17.1" +version = "0.18.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d38365ef5ebc0a55e342db7296a6ca9a2ee64916dbdbe4f87f1496b4fc68d0da" +checksum = "c3a3c31a30c93756dcdf76fadb3d35ea237ad750a530d49cf4bce8ee073092c8" dependencies = [ "arrow", "cmake", diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index ae13f25..c98c608 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -26,4 +26,4 @@ dirs = "5" fastrand = "2" reqwest = { version = "0.13.3", features = ["blocking", "json"] } icebug = { version = "12.9.0", optional = true } -lbug = { version = "0.17.1", features = ["arrow"] } +lbug = { version = "0.18.1", features = ["arrow"] }