语言绑定
PistaDB 通过封装同一个原生库,在 10 种语言中暴露同一套 API。C 核心是事实来源;每个绑定都通过 FFI / JNI / P/Invoke / ctypes / Embind / ccall 与之通信。
支持的语言
| 语言 | 绑定机制 | 代码位置 |
|---|---|---|
| C / C++ | 直接 #include | src/pistadb.h / wrap/cpp/pistadb.hpp |
| Python | ctypes(无 Cython) | wrap/python/ |
| Go | CGO | wrap/go/ |
| Java | JNI | wrap/android/src/main/java/ |
| Kotlin | JNI + 扩展函数 | wrap/android/src/main/kotlin/ |
| Objective-C | 直接 C 互操作 | wrap/ios/Sources/PistaDBObjC/ |
| Swift | 经由 ObjC 桥接 | 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/ |
支持的平台
| 平台 | 库产物 | ABI 目标 |
|---|---|---|
| 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 | 静态库(SPM) | arm64、arm64-Simulator、x86_64-Simulator |
| WASM | .wasm | —— (规划中) |
| ESP32 / MCU | libpistadb.a(ESP-IDF 组件) | xtensa-esp32-s3、esp32-c 系列 (实验性) |
部署原生库
除 WASM 和 iOS 静态框架外,每个绑定本质上都是在运行时加载 pistadb.dll / libpistadb.so / libpistadb.dylib 的薄封装。安装封装(pip install、go get、cargo build……)只完成了一半——还必须让操作系统的动态加载器能够找到原生库,否则会报 OSError: cannot open shared object file、DllNotFoundException、UnsatisfiedLinkError 等。
构建产物的位置
| 构建命令 | 输出路径 |
|---|---|
cmake -B build && cmake --build build --config Release | build/Release/pistadb.dll (Windows MSVC 多配置) |
| 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 |
两种布局都能被所有绑定的默认查找路径识别。带 <arch> 子目录的 scripts/<os>/build.* 布局更推荐用于分发,因为它能干净地容纳多架构产物。
三种部署策略
按你的发布形态任选其一:
1. 环境变量(开发、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"Python 封装额外支持 PISTADB_LIB_PATH——一个指向单个库文件的绝对路径——会绕过所有自动查找逻辑。适合非标准布局或需要强制指定某个构建产物时使用。
2. 系统级安装(服务器、Docker 基镜像)
# Linux
sudo cp build/libpistadb.so /usr/local/lib/
sudo ldconfig
# macOS
sudo cp build/libpistadb.dylib /usr/local/lib/
# Windows —— 拷到已在 %PATH% 中的目录,或 System32(需管理员权限)
copy build\Release\pistadb.dll C:\Windows\System32\3. 随程序一起分发(面向终端用户的推荐做法)
把库文件放到可执行文件 / Python 包 / .jar 旁边:
myapp/
├── myapp.exe ← Windows 主程序
├── pistadb.dll ← 自动加载(当前目录在 DLL 搜索路径上)
└── data/对 Python 而言,封装会在 wrap/python/pistadb/ 内部查找——你可以 cp libpistadb.so wrap/python/pistadb/,这样 pip install 生成的 wheel 就会把库一起打包。
各 OS 的运行时查找路径(未随程序分发时)
| 操作系统 | 加载器查找顺序 | 覆盖用环境变量 |
|---|---|---|
| Windows | exe 所在目录 → 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 |
如果 import pistadb 成功而 pistadb_open 报「library not found」,意味着封装本身被找到了,但它依赖的原生库没找到——请检查上表的加载器路径,而不是封装的安装方式。
各绑定的查找逻辑
| 绑定 | 查找顺序(命中即止) |
|---|---|
| Python | PISTADB_LIB_PATH → PISTADB_LIB_DIR → wrap/python/pistadb/(随包分发)→ <repo>/libs/<os>/<arch>/ → <repo>/build/(+ Release/Debug/RelWithDebInfo)→ /usr/local/lib、/usr/lib |
| Rust | PISTADB_LIB_DIR(构建期,由 build.rs 处理)→ <repo>/build/、build/Release、build/Debug。运行期仍需库在加载器路径上(或在 build.rs 里写 cargo:rustc-link-arg=-Wl,-rpath,...)。 |
| Go (CGO) | 构建期靠 CGO_LDFLAGS="-L<dir> -lpistadb",运行期靠 OS 加载器。请为生成的可执行文件设置 LD_LIBRARY_PATH / DYLD_LIBRARY_PATH。 |
| C# (P/Invoke) | 标准 .NET 原生加载器:程序目录 → runtimes/<rid>/native/(NuGet 布局)→ %PATH% / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH。 |
| C++ 头文件 | 由你的 CMake 决定。若没有把 PistaDB 通过 add_subdirectory 引入,请传 -DPISTADB_LIB_DIR=...。 |
| Julia | PISTADB_LIB_PATH → PISTADB_LIB_DIR → <repo>/libs/<os>/<arch>/ → <repo>/build/(+ Release/Debug/RelWithDebInfo)→ 系统 dlopen 查找路径。在模块 __init__ 时解析一次后由 Ref{String} 缓存。 |
| Android (JNI) | 已打包进 AAR 的 jniLibs/<abi>/libpistadb_jni.so——Gradle 会自动安装。无需任何环境变量。 |
| iOS / Swift | 通过 SPM 静态链接——无运行时部署,也无环境变量。 |
| WASM | 把 pistadb.wasm 放到 pistadb.js 旁边;以 application/wasm MIME 类型提供 .wasm。 |
各语言快速上手
完整集成步骤——go get、cargo build、pip install、Gradle / SPM / NuGet 接入,以及 Docker 方案——见仓库中的 docs/language-bindings.md, 以及 wrap/ 目录下的各语言 README。
Python
pip install -e wrap/python/Go
export CGO_LDFLAGS="-L../PistaDB/build -lpistadb"
go get pistadb.io/go/pistadbRust
cd wrap/rust
PISTADB_LIB_DIR=../../build cargo build --releaseJulia
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)完整的公共 C API 都已覆盖:核心 CRUD + WAL、Transaction(do 块自动 commit / 异常自动 rollback)、EmbeddingCache、MultiModal(命名向量字段 + RRF 混合检索),以及离线扫描 .pst 完整性的 check_file。
C# / .NET
<ItemGroup>
<ProjectReference Include="../PistaDB/wrap/csharp/PistaDB.csproj" />
</ItemGroup>Android(Gradle)
include ':android'
project(':android').projectDir = new File('<PistaDB-路径>/wrap/android')iOS / macOS(Swift Package Manager)
.package(path: "../PistaDB")