This is an automated email from the ASF dual-hosted git repository.
paleolimbot pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sedona-db.git
The following commit(s) were added to refs/heads/main by this push:
new 9cecb5b chore(docs): Update contributors guide with CMake setup
instructions for windows (#271)
9cecb5b is described below
commit 9cecb5b42e7ed2e5c234d61c24ea286ba3d58245
Author: L_Sowmya <[email protected]>
AuthorDate: Fri Nov 7 21:22:39 2025 +0530
chore(docs): Update contributors guide with CMake setup instructions for
windows (#271)
Co-authored-by: Dewey Dunnington <[email protected]>
Co-authored-by: Hiroaki Yutani <[email protected]>
---
docs/contributors-guide.md | 132 +++++++++++++++++++++++++++++++--------------
1 file changed, 92 insertions(+), 40 deletions(-)
diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md
index b3f3827..1545fdb 100644
--- a/docs/contributors-guide.md
+++ b/docs/contributors-guide.md
@@ -66,76 +66,128 @@ Your first step is to create a personal copy of the
repository and connect it to
upstream https://github.com/apache/sedona-db.git (fetch)
upstream https://github.com/apache/sedona-db.git (push)
```
+## System dependencies
-## Rust
+Some crates in the workspace wrap native libraries and require system
dependencies (GEOS, PROJ, Abseil, OpenSSL, CMake, etc.). We recommend using:
-SedonaDB is written in Rust and is a standard `cargo` workspace.
+### macOS: Homebrew
+``` bash brew install abseil openssl cmake geos proj ```
-You can install a recent version of the Rust compiler and cargo from
-[rustup.rs](https://rustup.rs/) and run tests using `cargo test`.
+Ensure Homebrew-installed tools are on your PATH (Homebrew usually does this
automatically).
-A local development version of the CLI can be run with `cargo run --bin
sedona-cli`.
+### Windows
-### Test data setup
+Suggested workflow (PowerShell):
-Some tests require submodules that contain test data or pinned versions of
-external dependencies. These submodules can be initialized with:
+First, install Rust if it is not already installed:
-```shell
-git submodule init
-git submodule update --recursive
+```powershell
+Invoke-WebRequest https://sh.rustup.rs -UseBasicParsing -OutFile
rustup-init.exe
+.\rustup-init.exe
+# Restart PowerShell
+rustc --version
+cargo --version
```
-Additionally, some of the data required in the tests can be downloaded by
running the following script.
+Next, install Visual Studio Build Tools
(<https://visualstudio.microsoft.com/downloads/>). Pick "Desktop development
with C++" during install.
-```bash
-python submodules/download-assets.py
+Next, install CMake (<https://cmake.org/>). Ensure "Add CMake to system PATH"
is selected during installation.
+
+```powershell
+cmake --version
```
-### System dependencies
-Some crates wrap external native libraries and require system dependencies
-to build.
+Now, install and bootstrap vcpkg (example path: C:\dev\vcpkg — you can choose
a different path; see note below about short paths):
-!!!note "`sedona-s2geography`"
- At this time, the only crate that requires this is the `sedona-s2geography`
- crate, which requires [CMake](https://cmake.org),
- [Abseil](https://github.com/abseil/abseil-cpp) and OpenSSL.
+```powershell
+git clone https://github.com/microsoft/vcpkg.git C:\dev\vcpkg
+cd C:\dev\vcpkg
+.\bootstrap-vcpkg.bat
+```
-#### macOS
-These can be installed on macOS with [Homebrew](https://brew.sh):
+Next, install the required libraries with vcpkg:
-```shell
-brew install abseil openssl cmake geos
+```powershell
+C:\dev\vcpkg\vcpkg.exe install geos proj abseil openssl
```
-#### Linux and Windows
+Configure environment variables (PowerShell example — update paths as needed):
-On Linux and Windows, it is recommended to use
[vcpkg](https://github.com/microsoft/vcpkg)
-to provide external dependencies. This can be done by setting the
`CMAKE_TOOLCHAIN_FILE`
-environment variable:
+```powershell
+$env:VCPKG_ROOT = 'C:\dev\vcpkg'
+$env:CMAKE_TOOLCHAIN_FILE =
"${env:VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
-```shell
-export CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
+# pkg-config/ msys path (hash may vary)
+$env:PATH =
"${env:VCPKG_ROOT}/downloads/tools/msys2/<msys-hash>/mingw64/bin/;$env:PATH"
+$env:PKG_CONFIG_SYSROOT_DIR =
"${env:VCPKG_ROOT}/downloads/tools/msys2/<msys-hash>/mingw64/"
+$env:PKG_CONFIG_PATH =
"${env:VCPKG_ROOT}/installed/x64-windows-dynamic-release/lib/pkgconfig/"
```
-#### Visual Studio Code (VSCode) Configuration
-When using VSCode, it may be necessary to set this environment variable in
`settings.json`
-such that it can be found by rust-analyzer when running build/run tasks:
+Note: the downloads/tools/msys2/<msys-hash> folder name varies per vcpkg
bootstrap. Replace <msys-hash> with the actual folder name on your system.
+
+VS Code integration (so rust-analyzer sees the toolchain):
+
+Add to your ```settings.json```:
```json
{
- "rust-analyzer.runnables.extraEnv": {
- "CMAKE_TOOLCHAIN_FILE":
"/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"
- },
- "rust-analyzer.cargo.extraEnv": {
- "CMAKE_TOOLCHAIN_FILE":
"/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"
- }
+ "rust-analyzer.runnables.extraEnv": {
+ "CMAKE_TOOLCHAIN_FILE": "C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake"
+ },
+ "rust-analyzer.cargo.extraEnv": {
+ "CMAKE_TOOLCHAIN_FILE": "C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake"
+ }
}
```
+### Linux
+
+Linux users may install system dependencies from a system package manager.
Note that recent versions are required because the Abseil version required is
relatively recent compared to the package version on some common LTS platforms.
+
+Ubuntu/Debian (Ubuntu 24.04 LTS is too old; however, later versions have the
required version of Abseil)
+
+```shell
+sudo apt-get install -y build-essential cmake libssl-dev libproj-dev
libgeos-dev python3-dev libabsl-dev
+```
+
+## Rust
+
+SedonaDB is written in Rust and is a standard `cargo` workspace.
+
+Before running cargo test, make sure to set the CMake toolchain variable:
+
+```export
CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake```
+
+Replace `/path/to/vcpkg/` with the actual path to your vcpkg installation.
+
+Once set, you can run: `cargo test`
+
+This ensures that Cargo and proj-sys can find the correct C/C++ dependencies
via CMake.
+You can install a recent version of the Rust compiler and cargo from
+[rustup.rs](https://rustup.rs/) and run tests using `cargo test`.
+
+A local development version of the CLI can be run with `cargo run --bin
sedona-cli`.
+
+## Test data setup
+
+Some tests require submodules that contain test data or pinned versions of
+external dependencies. These submodules can be initialized with:
+
+```shell
+git submodule init
+git submodule update --recursive
+```
+
+Additionally, some of the data required in the tests can be downloaded by
running the following script.
+
+```bash
+python submodules/download-assets.py
+```
+
+
## Python
Python bindings to SedonaDB are built with the
[Maturin](https://www.maturin.rs) build
