Building from Source

This page covers how to build Stoolap from source, including prerequisites, feature flags, cross-compilation, and WebAssembly builds.

Prerequisites

Rust toolchain: Rust 1.88 or later (edition 2021)
Git: For version embedding at build time

Install Rust via rustup:

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

Quick Build

# Clone the repository
git clone https://github.com/stoolap/stoolap.git
cd stoolap

# Debug build (fast compile, slower runtime)
cargo build

# Release build (optimized, with LTO)
cargo build --release

# Build and install the CLI
cargo install --path . --features cli

Feature Flags

Stoolap uses Cargo features to enable optional functionality. The default features are cli and parallel.

Core Features

Feature	Default	Description
`cli`	Yes	Command-line interface with interactive REPL, requires `clap`, `rustyline`, `comfy-table`, `dirs`
`parallel`	Yes	Multi-threaded query execution via Rayon (filter, join, sort, distinct)
`wasm`	No	WebAssembly build mode. Excludes parallel execution and file persistence
`ffi`	No	C FFI layer for language bindings. Produces `libstoolap.{so,dylib,dll}` with `include/stoolap.h`
`jemalloc`	Yes	Use stoolap-jemalloc, a jemalloc-style allocator in pure Rust, as the global allocator. Turn it off with `default-features = false` to keep your own allocator
`heap-profile`	No	Turn on stoolap-jemalloc’s sampling heap profiler, for `PRAGMA heap_profile`. Includes `jemalloc`

Testing and Benchmarking Features

Feature	Description
`stress-tests`	Enable stress tests: crash soak, metamorphic, concurrency
`test-failpoints`	Enable I/O fault injection testing
`dhat-heap`	Enable heap allocation profiling via dhat
`ann-benchmark`	Enable ANN (vector search) benchmarks with dataset downloading

The SQLite and DuckDB comparisons (benchmarks and the differential oracle) are a separate, unpublished crate, stoolap-compare in compare/, so --all-features on the library never builds either database. See BENCHMARKS.md for its commands.

Advanced Features

Feature	Description
`semantic`	Semantic search via HuggingFace embeddings. Requires `candle-core`, `candle-nn`, `candle-transformers`, `tokenizers`, `hf-hub`

Build Examples

# Default build (CLI + parallel + stoolap-jemalloc)
cargo build --release

# Library only (no CLI), with the system allocator
cargo build --release --no-default-features --features parallel

# With heap profiles (PRAGMA heap_profile)
cargo build --release --features heap-profile

# C FFI shared library (libstoolap.so / .dylib / .dll)
cargo build --release --features ffi

# Minimal build (no CLI, no parallel)
cargo build --release --no-default-features

Release Profile

The release profile is configured for maximum performance:

[profile.release]
lto = "thin"              # Thin LTO (95-100% of fat LTO perf, much faster compile)
codegen-units = 1         # Single codegen unit for better optimization
panic = "abort"           # Abort on panic (maximum performance)
opt-level = 3             # Maximum optimization
debug = "line-tables-only"  # File:line backtraces without full debug info

For maximum runtime performance (published binaries), use the max profile:

cargo build --profile max

WebAssembly Build

Stoolap can be compiled to WebAssembly for browser and Node.js usage.

Prerequisites

# Install wasm-pack
cargo install wasm-pack

# Or via npm
npm install -g wasm-pack

Building

# Build for browser
wasm-pack build --target web --no-default-features --features wasm

# Build for Node.js
wasm-pack build --target nodejs --no-default-features --features wasm

# Build for bundlers (webpack, etc.)
wasm-pack build --target bundler --no-default-features --features wasm

WASM-Specific Notes

The wasm feature disables parallel and file persistence
All data is in-memory only (lost on page reload)
Uses web-time for timestamp support instead of std::time
Random number generation uses the browser’s crypto API via getrandom
Published as the stoolap npm package with TypeScript definitions

See WebAssembly for usage documentation.

Cross-Compilation

Stoolap CI builds binaries for five targets:

Target	Binary Name	Notes
`x86_64-unknown-linux-gnu`	`stoolap-linux-amd64`	Standard Linux
`aarch64-unknown-linux-gnu`	`stoolap-linux-arm64`	Requires `gcc-aarch64-linux-gnu`
`x86_64-apple-darwin`	`stoolap-darwin-amd64`	Intel Mac
`aarch64-apple-darwin`	`stoolap-darwin-arm64`	Apple Silicon
`x86_64-pc-windows-msvc`	`stoolap-windows-amd64.exe`	Windows

To cross-compile locally:

# Add the target
rustup target add aarch64-unknown-linux-gnu

# Build for the target
cargo build --release --target aarch64-unknown-linux-gnu

Platform-Specific Dependencies

Stoolap uses conditional compilation for platform-specific file locking:

Unix: libc for flock()-based file locking
Windows: windows-sys for Windows file locking APIs
WebAssembly: No file locking (in-memory only)

Build Script

The build.rs script embeds the git commit hash at compile time as STOOLAP_GIT_COMMIT. This can be overridden by setting the STOOLAP_GIT_COMMIT environment variable before building.

Binary Targets

# CLI binary (requires 'cli' feature)
cargo run --features cli -- --help

# As a library (default in your Cargo.toml)
# [dependencies]
# stoolap = "0.4"

CI Profiles

For faster CI builds, a dedicated profile is available:

[profile.ci]
inherits = "release"
lto = "thin"          # Faster than full LTO
codegen-units = 16    # Parallel codegen
debug = false         # No debug symbols

Use it with: cargo build --profile ci