Crate faiss_next_sys

Expand description

§faiss-next-sys

Raw FFI bindings to Faiss C API.

This crate provides unsafe Rust bindings to the Faiss C library. For a safe, idiomatic API, use faiss-next.

Pre-generated bindings for common platforms
Automatic Faiss version detection
Multi-version binding support (1.14.x, 1.15.x, …)
Optional runtime binding generation via bindgen
CUDA support (Linux and Windows)

OS	Architecture	CPU	CUDA
macOS (Apple Silicon)	aarch64 (M1/M2/M3)	✅	❌
Linux	x86_64	✅	✅
Windows	x86_64	✅	✅

✅ Fully supported with pre-generated bindings
❌ Not supported

CUDA is supported on Linux x86_64 and Windows x86_64

Install Faiss with C API enabled:

macOS (Homebrew):

brew install faiss

Linux (from source):

git clone https://github.com/facebookresearch/faiss.git
cd faiss
mkdir build && cd build
cmake -DFAISS_ENABLE_C_API=ON -DBUILD_SHARED_LIBS=ON ..
make -j$(nproc)
sudo make install
sudo ldconfig

Windows:

Build Faiss from source with C API enabled. A pre-configured build is available at:

git clone -b windows-build https://github.com/yexiangyu/faiss.git
cd faiss
mkdir build && cd build
cmake -A x64 -DFAISS_ENABLE_C_API=ON -DBUILD_SHARED_LIBS=ON ^
      -DFAISS_ENABLE_GPU=ON ^
      -DCMAKE_INSTALL_PREFIX=C:/tools/faiss ..
cmake --build . --config Release
cmake --install . --config Release

After installation, set environment variables:

set FAISS_INCLUDE_DIR=C:\tools\faiss\include
set FAISS_LIB_DIR=C:\tools\faiss\lib

Alternatively, place Faiss in the default location:

C:\tools\faiss (include: C:\tools\faiss\include, lib: C:\tools\faiss\lib)

Or other supported locations:

C:\faiss
C:\Program Files\faiss
C:\Program Files (x86)\faiss

This crate is typically used as a dependency of faiss-next. Add to Cargo.toml:

[dependencies]
faiss-next-sys = "0.6"

Variable	Description
`FAISS_INCLUDE_DIR`	Direct path to Faiss include directory (e.g., `C:\faiss\include`)
`FAISS_LIB_DIR`	Direct path to Faiss lib directory (e.g., `C:\faiss\lib`)
`FAISS_DIR`	Path to Faiss installation root (must contain `include/` and `lib/`)
`LD_LIBRARY_PATH`	Linux library search path
`DYLD_LIBRARY_PATH`	macOS library search path
`PATH`	Windows DLL search path

Priority order:

FAISS_INCLUDE_DIR + FAISS_LIB_DIR (direct paths, recommended for Windows)
FAISS_DIR (installation root)
Platform-specific default paths

Flag	Description
`cuda`	Enable CUDA support (Linux x86_64 and Windows x86_64 only)
`bindgen`	Generate bindings at compile time

Platform restrictions:

cuda feature is only available on Linux x86_64 and Windows x86_64
Using cuda feature on macOS will result in a compile error

Note: The bindgen feature requires LLVM/Clang to be installed:

Linux: sudo apt install llvm-dev libclang-dev (Ubuntu/Debian)
macOS: brew install llvm
Windows: Install LLVM from https://llvm.org/builds/ and ensure libclang is in your PATH

The build script automatically detects the installed Faiss version by parsing include/faiss/Index.h:

#define FAISS_VERSION_MAJOR 1
#define FAISS_VERSION_MINOR 14
#define FAISS_VERSION_PATCH 0

Minimum version: 1.14.0
Loose mode: Versions newer than tested versions work with a compile warning

When a newer Faiss version is detected, the build system:

Emits a warning about compatibility
Uses the closest available binding version
Attempts to compile and run

Bindings are pre-generated and committed to the repository:

src/bindings/
├── mod.rs              # Version selection
└── v1_14/
    ├── mod.rs          # Platform selection
    ├── macos_aarch64.rs
    ├── linux_x86_64.rs
    ├── linux_x86_64_cuda.rs
    ├── windows_x86_64.rs
    └── windows_x86_64_cuda.rs

To generate bindings for your platform (e.g., when using a custom Faiss version):

cargo build --features bindgen

// Types
pub type idx_t = i64;

// Index operations
pub fn faiss_IndexFlat_new(...) -> *mut FaissIndexFlat;
pub fn faiss_Index_add(...);
pub fn faiss_Index_search(...);

// IVF operations
pub fn faiss_IndexIVF_new(...);
pub fn faiss_IndexIVF_set_nprobe(...);

// Distance computations
pub fn faiss_pairwise_L2sqr(...);
pub fn faiss_fvec_inner_products_ny(...);

// ... and more

The crate links against:

libfaiss - Core Faiss library
libfaiss_c - C API wrapper

Ensure these libraries are in your library search path.

Structs§

Enums§

Constants§

Functions§

Type Aliases§