From eb8b26ae5c03fcb8d97b4b73904f4e935e19c347 Mon Sep 17 00:00:00 2001 From: grimmjoww578 Date: Sat, 25 Apr 2026 03:02:19 -0400 Subject: [PATCH] docs: add native Windows MSVC build guide (no Docker, no WSL2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the toolchain and steps for producing a working `vchord.dll` on Windows without Docker or WSL2. The codebase already lists `x86_64-pc-windows-msvc` as a default cargo target in `xtask`; this just fills in the gap so anyone with PostgreSQL on Windows can reproduce the build. Verified end-to-end on Windows 11 + VS2022 + LLVM 22.1.4 + Rust 1.95.0 + cargo-pgrx 0.17.0 + PostgreSQL 17.9. Output is a 9.4 MB PE32+ DLL that imports symbols from `postgres.exe` exactly the way pgvector's Windows extension does (verified via `dumpbin /dependents`). Key gotchas captured: - Rust 1.95+ required (1.93/1.94 fail on `stdarch_x86_avx512_f16` in `crates/simd/src/floating_f16.rs`; that feature was stabilized in 1.95) - `cargo pgrx init` does not auto-download Postgres on Windows - `xtask build` requires `PG_CONFIG` env var - vcvars64.bat env doesn't propagate to bash sessions No source-code changes required — purely documentation. The only behaviorally-relevant follow-up would be adding a Windows runner to `.github/workflows/release.yml` so users get a prebuilt `vchord-pg17-x86_64-windows-msvc.zip` artifact alongside the existing Linux .deb / .zip outputs. Happy to follow up with that PR if maintainers want it. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 2 ++ docs/WINDOWS.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 docs/WINDOWS.md diff --git a/README.md b/README.md index e305937c..e270f98a 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,8 @@ VectorChord introduces remarkable enhancements over pgvecto.rs and pgvector: For new users, we recommend using the Docker image to get started quickly. If you do not prefer Docker, please read [installation guide](https://docs.vectorchord.ai/vectorchord/getting-started/installation.html) for other installation methods. +Windows users: a native MSVC build (no Docker, no WSL2) is documented in [docs/WINDOWS.md](./docs/WINDOWS.md). Toolchain: VS2022 + LLVM + Rust 1.95+ + PostgreSQL 17. + ```bash docker run \ --name vectorchord-demo \ diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md new file mode 100644 index 00000000..1c8d934e --- /dev/null +++ b/docs/WINDOWS.md @@ -0,0 +1,84 @@ +# Building VectorChord on Windows (Native, MSVC) + +VectorChord builds and runs natively on Windows via MSVC — no Docker, no WSL2 required. The codebase already lists `x86_64-pc-windows-msvc` as a supported cargo target in `xtask`; this guide documents the toolchain and steps so anyone with PostgreSQL on Windows can produce a working `vchord.dll`. + +## Required toolchain + +| Component | Minimum | Why | +|---|---|---| +| **Rust** | **1.95.0** stable | The `simd` crate uses AVX-512 FP16 intrinsics (`stdarch_x86_avx512_f16`) which were unstable before Rust 1.95. Earlier versions fail with `E0658`. | +| **Visual Studio 2022 Build Tools** | 17.x | C/C++ compiler + linker (`cl.exe`, `link.exe`) for the `cc` build dependencies and the final cdylib link | +| **LLVM / clang** | 16+ | `pgrx-pg-sys` uses `bindgen`, which requires `libclang.dll`. Set `LIBCLANG_PATH` to the LLVM `bin` directory. | +| **PostgreSQL 17 (or 14–18)** | matching dev install | Provides `pg_config.exe`, `include/server/` headers, and `lib/postgres.lib` import library | +| **cargo-pgrx** | matching `pgrx` pin in `Cargo.toml` (currently 0.17.0) | `cargo install --locked cargo-pgrx@0.17.0` | + +## Setup + +1. Install [Visual Studio 2022 Community](https://visualstudio.microsoft.com/downloads/) with the "Desktop development with C++" workload. +2. Install [Rust](https://rustup.rs/) (the installer auto-detects MSVC). +3. Install LLVM — either via [official Windows installer](https://github.com/llvm/llvm-project/releases) or extract the portable `.tar.xz` for `x86_64-pc-windows-msvc`. +4. Install [PostgreSQL 17 from EnterpriseDB](https://www.enterprisedb.com/downloads/postgres-postgresql-downloads). +5. Install cargo-pgrx and initialize: + + ```cmd + cargo install --locked cargo-pgrx@0.17.0 + cargo pgrx init --pg17 "C:\Program Files\PostgreSQL\17\bin\pg_config.exe" + ``` + +## Build + +From a "x64 Native Tools Command Prompt for VS 2022" (or after running `vcvars64.bat` in your shell): + +```cmd +set "PATH=C:\path\to\llvm\bin;C:\Program Files\PostgreSQL\17\bin;%PATH%" +set "LIBCLANG_PATH=C:\path\to\llvm\bin" +set "PG_CONFIG=C:\Program Files\PostgreSQL\17\bin\pg_config.exe" + +cargo run -p xtask --release -- build +``` + +Build output: + +- `build\pkglibdir\vchord.dll` — the extension binary +- `build\sharedir\extension\vchord--.sql` — extension SQL definitions +- `build\sharedir\extension\vchord.control` — Postgres control file + +The DLL is a normal PE32+ x64 binary that imports symbols from `postgres.exe`, exactly the way pgvector's Windows extension does. + +## Install (administrator) + +Open a Command Prompt **as administrator**: + +```cmd +copy /Y .\build\pkglibdir\vchord.dll "C:\Program Files\PostgreSQL\17\lib\" +copy /Y .\build\sharedir\extension\vchord--*.sql "C:\Program Files\PostgreSQL\17\share\extension\" +copy /Y .\build\sharedir\extension\vchord.control "C:\Program Files\PostgreSQL\17\share\extension\" +``` + +Edit `C:\Program Files\PostgreSQL\17\data\postgresql.conf` and add: + +``` +shared_preload_libraries = 'vchord' +``` + +Restart Postgres and create the extension: + +```cmd +net stop postgresql-x64-17 +net start postgresql-x64-17 +``` + +```sql +CREATE EXTENSION vchord CASCADE; +``` + +## Pitfalls + +1. **Rust 1.94 and earlier fail to build** with `E0658: use of unstable library feature 'stdarch_x86_avx512_f16'` in `crates/simd/src/floating_f16.rs`. Run `rustup update` to get 1.95+. +2. **`cargo pgrx init` does not auto-download Postgres on Windows.** Install PostgreSQL via the EnterpriseDB installer first, then point `cargo pgrx init --pg17` at its `pg_config.exe`. +3. **`xtask build` requires `PG_CONFIG`** to be set before running — the Linux Makefile sets it implicitly; on Windows you must export it manually. +4. **vcvars64.bat does not propagate environment to bash sessions.** Use the "x64 Native Tools Command Prompt for VS 2022" or wrap your build in a `.cmd` file that calls `vcvars64.bat` first. + +## Verification + +Run `dumpbin /dependents build\pkglibdir\vchord.dll` from the VS dev prompt — the imports should be `postgres.exe`, `KERNEL32.dll`, `ntdll.dll`, `VCRUNTIME140.dll`, `api-ms-win-crt-*` (UCRT), and `bcryptprimitives.dll`. Anything else (especially Linux `.so` references) means a misconfigured build.