Building from Source¶

Velr is developed as a Rust workspace with optional Python bindings. You can build everything locally from a Git checkout.

This page covers:

Prerequisites
Cloning the repository
Building the Rust core and CLI shell
Building the Python wheel
Running tests
Optional features (Arrow / Polars)

Note The workspace includes internal crates for tests and tooling. Only the core engine, CLI shell, FFI layer, and Python driver are relevant for typical users.

Prerequisites¶

You’ll need:

Git
Rust toolchain (stable) Install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

A C toolchain
Linux: build-essential (or equivalent)
macOS: Xcode command line tools (xcode-select --install)
Windows: MSVC toolchain via Visual Studio Build Tools
(Optional) Python 3.8+ with pip and venv Only needed if you want to build/install the Python driver from source.

Velr uses rusqlite with the bundled feature, so you do not need a system SQLite installed.

Clone the Repository¶

Assuming the source is hosted on GitHub:

git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>

The root contains a Cargo workspace:

[workspace]
members = [
  "rust/velr-core",
  "rust/velr-cli",
  "rust/velr-ffi",
  "rust/velr-e2e",
]

default-members = [
  "rust/velr-core",
  "rust/velr-cli",
  "rust/velr-ffi",
  "rust/velr-e2e",
]

Key crates:

rust/velr-core — core engine and query processor
rust/velr-cli — Velr shell / command-line interface
rust/velr-ffi — FFI library used by the Python driver and other bindings
rust/velr-e2e — end-to-end tests

Python bindings live under:

velrpy/ — Python package (velrpy) + tests
scripts/ — helper scripts (e.g. Python wheel build script)

Building the Rust Core & CLI Shell¶

Build everything (defaults)¶

From the repo root:

# Build the default workspace members in debug mode
cargo build

For an optimized build:

cargo build --release

This will compile:

velr-core (library)
velr-cli (binary shell)
velr-ffi (FFI library)
velr-e2e (tests)

Build the shell only¶

If you just want the CLI shell:

# Debug build
cargo build -p velr-cli

# Release build
cargo build -p velr-cli --release

The resulting binary will be in:

target/release/velr   # or `velr.exe` on Windows

You can run it directly:

./target/release/velr

Or install it into your $PATH:

cargo install --path rust/velr-cli

Enabling Optional Features (Arrow / Polars)¶

velr-core exposes features to enable Arrow IPC and Polars:

[features]
default = []
bench = []
arrow-ipc = ["dep:arrow2", "dep:polars"]
polars = ["dep:polars"]

Build with Arrow IPC support¶

cargo build --release -p velr-core --features arrow-ipc

Build with Polars support¶

cargo build --release -p velr-core --features polars

Combine features¶

cargo build --release -p velr-core --features "arrow-ipc polars"

The velr-ffi crate also relies on these features when building bindings. When you use the provided Python build script (below), it already enables the right feature set (arrow-ipc).

Building the Python Wheel¶

The repo includes a helper script to build and test the Python wheel.

From the repo root:

scripts/build-wheel.sh

This script will:

Detect the repo root.
Create a local virtualenv at .pybuild/ for packaging tools.
Build the Rust FFI library (velr-ffi) in release mode with arrow-ipc enabled:

cargo build -p velr-ffi --release --features arrow-ipc

Copy the produced dynamic library into the Python package’s vendor directory:

velrpy/src/velrpy/_vendor/libvelr.dylib

Note The script, as written, targets macOS (.dylib). If you’re on Linux or Windows, adjust the file name and search paths in scripts/build-wheel.sh to match your platform (.so / .dll).

Build the Python wheel:

cd velrpy
python -m build

Run tests against:
an editable install (pip install -e ".[all,test]"), and
the built wheel in a fresh virtualenv.

At the end, you’ll see something like:

Wheel ready in: /path/to/repo/velrpy/dist

You can then install the wheel:

pip install velrpy/dist/velrpy-<version>-py3-none-any.whl[all]

Running Tests¶

Rust tests¶

From the repo root:

# All workspace tests
cargo test

# Just core
cargo test -p velr-core

# End-to-end tests
cargo test -p velr-e2e

You can combine with features, e.g.:

cargo test -p velr-core --features "arrow-ipc polars"

Python tests¶

If you prefer to run Python tests manually (instead of using scripts/build-wheel.sh):

cd velrpy

# Create a venv
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in editable mode with extras
pip install -U pip
pip install -e ".[all,test]"

# Run tests
pytest -q

If you’ve already built the wheel and want to test the “pip install” experience:

cd velrpy
python -m venv .venv-wheel
source .venv-wheel/bin/activate
pip install -U pip

pip install dist/velrpy-*.whl[all,test]
pytest -q

Typical Build Workflows¶

Build & run the shell in one go¶

# From repo root
cargo build -p velr-cli --release
./target/release/velr my.db

Build everything with Arrow + Polars¶

cargo build --release \
  -p velr-core \
  -p velr-cli \
  -p velr-ffi \
  --features "arrow-ipc polars"

Build the Python wheel and test it¶

./scripts/build-wheel.sh
# Wheel is now in velrpy/dist/

Once the above steps work on your machine, you have a full local build:

Rust core: velr-core
Shell / CLI: velr binary from velr-cli
FFI library: velr-ffi (used by bindings)
Python driver: velrpy, installable via the built wheel