Language Bindings

PistaDB exposes the same API in 10 languages, by wrapping a single native library. The C core is the source of truth; every binding talks to it through FFI / JNI / P/Invoke / ctypes / Embind / ccall.

Supported languages

Language	Binding mechanism	Where to find it
C / C++	Direct #include	src/pistadb.h / wrap/cpp/pistadb.hpp
Python	ctypes (no Cython)	wrap/python/
Go	CGO	wrap/go/
Java	JNI	wrap/android/src/main/java/
Kotlin	JNI + extension functions	wrap/android/src/main/kotlin/
Objective-C	Direct C interop	wrap/ios/Sources/PistaDBObjC/
Swift	ObjC bridge	wrap/ios/Sources/PistaDB/
C#	P/Invoke	wrap/csharp/
Rust	FFI (extern "C")	wrap/rust/
Julia	ccall / Libdl	wrap/julia/PistaDB/
WASM	Emscripten / Embind	wrap/wasm/

Supported platforms

Platform	Library output	ABI targets
Windows	pistadb.dll	x86_64
Linux	libpistadb.so	x86_64, aarch64
macOS	libpistadb.dylib	x86_64, arm64
Android	libpistadb_jni.so	arm64-v8a, armeabi-v7a, x86_64, x86
iOS / macOS	Static library (SPM)	arm64, arm64-Simulator, x86_64-Simulator
WASM	.wasm	— (planned)
ESP32 / MCU	libpistadb.a (ESP-IDF component)	xtensa-esp32-s3, esp32-c series (experimental)

Deploying the native library

Every binding except WASM and the iOS static framework is a thin wrapper that loads pistadb.dll / libpistadb.so / libpistadb.dylib at runtime. Installing the wrapper (pip install, go get, cargo build, …) is only half the job — the OS dynamic loader must also be able to find the native library, or you'll get OSError: cannot open shared object file, DllNotFoundException, UnsatisfiedLinkError, etc.

Where the build puts the library

Build command	Output path
cmake -B build && cmake --build build --config Release	build/Release/pistadb.dll (Windows, MSVC multi-config)
same on Linux/macOS	build/libpistadb.so / build/libpistadb.dylib
scripts/windows/build.bat	libs/windows/x64/pistadb.dll
bash scripts/linux/build.sh	libs/linux/<arch>/libpistadb.so
bash scripts/macos/build.sh	libs/macos/<arch>/libpistadb.dylib

Both layouts are recognised by every binding's default search path. The scripts/<os>/build.* layout (with <arch> subdirectory) is the recommended one for distribution because it round-trips multiple architectures cleanly.

Three deployment strategies

Pick whichever fits your shipping model:

1. Environment variable (development, CI)

# Linux / macOS
export PISTADB_LIB_DIR=/path/to/PistaDB/build
# Windows (cmd)
set PISTADB_LIB_DIR=C:\path\to\PistaDB\build\Release
# Windows (PowerShell)
$env:PISTADB_LIB_DIR = "C:\path\to\PistaDB\build\Release"

The Python wrapper additionally accepts PISTADB_LIB_PATH — an absolute path to a single file — which bypasses all search logic. Useful when you have a non-standard layout or want to force a specific build.

2. System-wide install (servers, Docker base images)

# Linux
sudo cp build/libpistadb.so /usr/local/lib/
sudo ldconfig

# macOS
sudo cp build/libpistadb.dylib /usr/local/lib/

# Windows — copy into a directory already on %PATH%, or to System32 (admin)
copy build\Release\pistadb.dll C:\Windows\System32\

3. Vendored next to your application (recommended for end-user distribution)

Place the library next to the executable / Python package / .jar:

myapp/
├── myapp.exe              ← Windows binary
├── pistadb.dll            ← loaded automatically (current dir is on DLL search path)
└── data/

For Python, the wrapper looks inside wrap/python/pistadb/ itself — you can cp libpistadb.so wrap/python/pistadb/ and pip install will package the library with the wheel.

Per-OS runtime search path (when not vendored)

OS	Loader-controlled search path	Override env var
Windows	exe dir → System32 → %PATH%	PATH
Linux	rpath → LD_LIBRARY_PATH → /etc/ld.so.cache → /usr/lib, /usr/local/lib	LD_LIBRARY_PATH
macOS	@rpath → DYLD_LIBRARY_PATH → /usr/local/lib, /usr/lib	DYLD_LIBRARY_PATH

If pistadb_open fails with a "library not found" error after import pistadb succeeds, the wrapper found the wrapper but couldn't load the native dependency — check the loader search path above, not the wrapper install.

Binding-specific resolution

Binding	Search order (first hit wins)
Python	PISTADB_LIB_PATH → PISTADB_LIB_DIR → wrap/python/pistadb/ (vendored) → <repo>/libs/<os>/<arch>/ → <repo>/build/ (+ Release/Debug/RelWithDebInfo) → /usr/local/lib, /usr/lib
Rust	PISTADB_LIB_DIR (build-time, via build.rs) → <repo>/build/, build/Release, build/Debug. Runtime still needs the lib on the loader path (or cargo:rustc-link-arg=-Wl,-rpath,...).
Go (CGO)	CGO_LDFLAGS="-L<dir> -lpistadb" at build, then the OS loader at run-time. Set LD_LIBRARY_PATH / DYLD_LIBRARY_PATH for the produced binary.
C# (P/Invoke)	Standard .NET native loader: app dir → runtimes/<rid>/native/ (NuGet layout) → %PATH% / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH.
C++ header	Whatever your CMake links against. Pass -DPISTADB_LIB_DIR=... if add_subdirectory(PistaDB) is not in your tree.
Julia	PISTADB_LIB_PATH → PISTADB_LIB_DIR → <repo>/libs/<os>/<arch>/ → <repo>/build/ (+ Release/Debug/RelWithDebInfo) → system dlopen search path. Resolved once at module __init__ time and frozen via a Ref{String}.
Android (JNI)	Bundled inside the AAR under jniLibs/<abi>/libpistadb_jni.so — Gradle installs it automatically. No env var needed.
iOS / Swift	Statically linked via SPM — no runtime deployment, no env var.
WASM	Place pistadb.wasm next to pistadb.js; serve .wasm as application/wasm.

Quick start per language

For full integration steps — go get, cargo build, pip install, Gradle / SPM / NuGet wiring, and Docker recipes — see docs/language-bindings.md in the repository, and the per-language README under wrap/.

Python

pip install -e wrap/python/

Go

export CGO_LDFLAGS="-L../PistaDB/build -lpistadb"
go get pistadb.io/go/pistadb

Rust

cd wrap/rust
PISTADB_LIB_DIR=../../build cargo build --release

Julia

using Pkg
Pkg.develop(path = "wrap/julia/PistaDB")
using PistaDB

db = pistadb_open("mydb.pst", 128; metric = METRIC_COSINE, index = INDEX_HNSW)
insert!(db, 1, randn(Float32, 128); label = "dog")
results = search(db, randn(Float32, 128), 5)
save(db); close(db)

The full public C API is covered: core CRUD + WAL, Transaction (with do-block auto-commit / auto-rollback), EmbeddingCache, MultiModal (named vector fields + RRF hybrid search), and check_file for offline .pst integrity scans.

C# / .NET

<ItemGroup>
  <ProjectReference Include="../PistaDB/wrap/csharp/PistaDB.csproj" />
</ItemGroup>

Android (Gradle)

include ':android'
project(':android').projectDir = new File('<path-to-PistaDB>/wrap/android')

iOS / macOS (Swift Package Manager)

.package(path: "../PistaDB")