From ef26126218a29ea399ca9a5ba7bbb0d59c557823 Mon Sep 17 00:00:00 2001 From: Rod Boev Date: Thu, 3 Sep 2026 22:10:07 -0400 Subject: [PATCH 1/2] docs: note Node.js and libsqlite3-dev as source-build prerequisites --- README.md | 6 ++++-- docs/development.md | 9 ++++++--- docs/setup.md | 17 +++++++++++++---- docs/troubleshooting.md | 7 +++++++ 4 files changed, 30 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6762c413f..93a286ab3 100644 --- a/README.md +++ b/README.md @@ -80,8 +80,10 @@ powershell -ExecutionPolicy ByPass -c "irm https://msgvault.io/install.ps1 | iex The installer detects your OS and architecture, downloads the latest release from [GitHub Releases](https://github.com/kenn-io/msgvault/releases), verifies the SHA-256 checksum, and installs the binary. You can review the script ([bash](https://msgvault.io/install.sh), [PowerShell](https://msgvault.io/install.ps1)) before running, or download a release binary directly from GitHub. -To build from source instead (requires **Go 1.27+**, **Bun 1.3.14+**, and a -C/C++ compiler for CGO and to statically link DuckDB): +To build from source instead (requires **Go 1.27+**, **Bun 1.3.14+**, **Node.js +20.19+ on 20.x, 22.13+ on 22.x, or 24+**, and a C/C++ compiler for CGO and to +statically link DuckDB; on Debian/Ubuntu also install `libsqlite3-dev` for the +`sqlite3.h` header used by the default `sqlite_vec` build): ```bash git clone https://github.com/kenn-io/msgvault.git diff --git a/docs/development.md b/docs/development.md index 35e4254e9..fa0e7a528 100644 --- a/docs/development.md +++ b/docs/development.md @@ -5,9 +5,12 @@ description: Build, test, lint, and code conventions. ## Build -Source builds require Go 1.27+, Bun 1.3.14+, and a C/C++ compiler. The Make -targets install the pinned browser dependencies when `web/package.json` or -`web/bun.lock` changes, then embed the production UI in the Go binary. +Source builds require Go 1.27+, Bun 1.3.14+, Node.js (20.19+ on 20.x, 22.13+ on +22.x, or 24+), and a C/C++ compiler. The Make targets install the pinned browser +dependencies when `web/package.json` or `web/bun.lock` changes, then embed the +production UI in the Go binary; Node runs the embed validator in that path. On +Debian/Ubuntu also install `libsqlite3-dev`, which provides the `sqlite3.h` +header needed to compile the default `sqlite_vec` extension. ### macOS and Linux diff --git a/docs/setup.md b/docs/setup.md index c9bb5aacd..250fd9276 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -45,10 +45,19 @@ conda install -c conda-forge msgvault ## Build From Source -Requires Go 1.27+, Bun 1.3.14+, and a C/C++ compiler (GCC or Clang). Bun builds -the browser application embedded in the binary. CGO is required because -msgvault uses `mattn/go-sqlite3` (SQLite with FTS5) and `duckdb-go/v2` (Parquet -analytics), both of which compile native extensions. +Requires Go 1.27+, Bun 1.3.14+, Node.js (20.19+ on 20.x, 22.13+ on 22.x, or +24+), and a C/C++ compiler (GCC or Clang). Bun builds the browser application +embedded in the binary, and Node runs the embed validator that `make install` +invokes. CGO is required because msgvault uses `mattn/go-sqlite3` (SQLite with +FTS5) and `duckdb-go/v2` (Parquet analytics), both of which compile native +extensions. + +On Debian/Ubuntu also install `libsqlite3-dev`, which provides the `sqlite3.h` +header needed to compile the default `sqlite_vec` extension: + +```bash +sudo apt install -y libsqlite3-dev +``` ```bash git clone https://github.com/kenn-io/msgvault.git diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 35e8609a4..ea08b1931 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -269,6 +269,13 @@ If you get errors about missing C compiler: CGO is required for `mattn/go-sqlite3` (FTS5 support). +If the build reaches the cgo step and fails with `fatal error: sqlite3.h: No +such file or directory` (from `asg017/sqlite-vec-go-bindings`), you are missing +the SQLite development headers that the default `sqlite_vec` build needs: + +- **Debian/Ubuntu**: `sudo apt install -y libsqlite3-dev` +- **Fedora/RHEL**: `sudo dnf install -y sqlite-devel` + ## TUI Not Showing Data If the TUI launches but shows no data: From 4b4cf100a4bf01a60a2f5ef7600ba06355ac616e Mon Sep 17 00:00:00 2001 From: Wes McKinney Date: Thu, 3 Sep 2026 23:08:19 -0500 Subject: [PATCH 2/2] docs: scope source build prerequisites by platform The Make-based build needs Node and system SQLite headers, while the Windows helper builds directly with Go and supplies its own header. The prior blanket prerequisite list incorrectly told Windows users to install tools that their supported build path does not run. Generated with Codex Co-authored-by: Codex --- README.md | 9 +++++---- docs/development.md | 13 +++++++------ docs/setup.md | 12 ++++++------ 3 files changed, 18 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 93a286ab3..13b261adc 100644 --- a/README.md +++ b/README.md @@ -80,10 +80,11 @@ powershell -ExecutionPolicy ByPass -c "irm https://msgvault.io/install.ps1 | iex The installer detects your OS and architecture, downloads the latest release from [GitHub Releases](https://github.com/kenn-io/msgvault/releases), verifies the SHA-256 checksum, and installs the binary. You can review the script ([bash](https://msgvault.io/install.sh), [PowerShell](https://msgvault.io/install.ps1)) before running, or download a release binary directly from GitHub. -To build from source instead (requires **Go 1.27+**, **Bun 1.3.14+**, **Node.js -20.19+ on 20.x, 22.13+ on 22.x, or 24+**, and a C/C++ compiler for CGO and to -statically link DuckDB; on Debian/Ubuntu also install `libsqlite3-dev` for the -`sqlite3.h` header used by the default `sqlite_vec` build): +To build from source on macOS or Linux instead (requires **Go 1.27+**, **Bun +1.3.14+**, **Node.js 20.19+ on 20.x, 22.13+ on 22.x, or 24+**, and a C/C++ +compiler for CGO and to statically link DuckDB; on Debian/Ubuntu also install +`libsqlite3-dev` for the `sqlite3.h` header used by the default `sqlite_vec` +build): ```bash git clone https://github.com/kenn-io/msgvault.git diff --git a/docs/development.md b/docs/development.md index fa0e7a528..118bf7ab1 100644 --- a/docs/development.md +++ b/docs/development.md @@ -5,12 +5,13 @@ description: Build, test, lint, and code conventions. ## Build -Source builds require Go 1.27+, Bun 1.3.14+, Node.js (20.19+ on 20.x, 22.13+ on -22.x, or 24+), and a C/C++ compiler. The Make targets install the pinned browser -dependencies when `web/package.json` or `web/bun.lock` changes, then embed the -production UI in the Go binary; Node runs the embed validator in that path. On -Debian/Ubuntu also install `libsqlite3-dev`, which provides the `sqlite3.h` -header needed to compile the default `sqlite_vec` extension. +The macOS and Linux builds require Go 1.27+, Bun 1.3.14+, Node.js (20.19+ on +20.x, 22.13+ on 22.x, or 24+), and a C/C++ compiler. The Make targets install +the pinned browser dependencies when `web/package.json` or `web/bun.lock` +changes, then embed the production UI in the Go binary; Node runs the embed +validator in that path. On Debian/Ubuntu also install `libsqlite3-dev`, which +provides the `sqlite3.h` header needed to compile the default `sqlite_vec` +extension. ### macOS and Linux diff --git a/docs/setup.md b/docs/setup.md index 250fd9276..7b28fc6c4 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -45,12 +45,12 @@ conda install -c conda-forge msgvault ## Build From Source -Requires Go 1.27+, Bun 1.3.14+, Node.js (20.19+ on 20.x, 22.13+ on 22.x, or -24+), and a C/C++ compiler (GCC or Clang). Bun builds the browser application -embedded in the binary, and Node runs the embed validator that `make install` -invokes. CGO is required because msgvault uses `mattn/go-sqlite3` (SQLite with -FTS5) and `duckdb-go/v2` (Parquet analytics), both of which compile native -extensions. +On macOS and Linux, source builds require Go 1.27+, Bun 1.3.14+, Node.js +(20.19+ on 20.x, 22.13+ on 22.x, or 24+), and a C/C++ compiler (GCC or Clang). +Bun builds the browser application embedded in the binary, and Node runs the +embed validator that `make install` invokes. CGO is required because msgvault +uses `mattn/go-sqlite3` (SQLite with FTS5) and `duckdb-go/v2` (Parquet +analytics), both of which compile native extensions. On Debian/Ubuntu also install `libsqlite3-dev`, which provides the `sqlite3.h` header needed to compile the default `sqlite_vec` extension: