# `faiss-next-sys`

`faiss-next-sys` wrap `c_api` of `faiss` into `rust` with `bindgen`.

Currently supported `faiss` version is `v1.7.4`

## Build `faiss` from source

`faiss-next-sys` requires `faiss` compiled with `FAISS_ENABLE_C_API=ON` and `BUILD_SHARED_LIBS=ON`.

Some [facebookresearch/faiss](https://github.com/facebookresearch/faiss) distributions, like of `brew` on mac, does not provide `faiss_c` library.

So, building `faiss` from source is necessary time to time.

[facebookresearch/faiss](https://github.com/facebookresearch/faiss) provides installation [document](https://github.com/facebookresearch/faiss/blob/main/INSTALL.md) officially to guide how to build `faiss` from source.

But, on `windows`, building `faiss` will fail, because of `msvc` c++ compiler's implemention of `C++17` syntax: [issue](https://github.com/facebookresearch/faiss/issues/2985).

So, a hecked `v1.7.4` version is made: [link](https://github.com/yexiangyu/faiss/archive/refs/heads/v1.7.4-win.zip) to solve the issue.

If `windows` is not the target platform, just clone `faiss` and check `v1.7.4` branch out, will just work fine.

- link: [hecked version](https://github.com/yexiangyu/faiss/archive/refs/heads/v1.7.4-win.zip)
- link [offical version](https://github.com/facebookresearch/faiss/archive/refs/tags/v1.7.4.zip)

Pick one of above, download, unzip, then start building:

## `MacOS`
`xcode` and [`brew`](https://brew.sh) needed, install in advance.
 ```shell
 # install cmake openblas and llvm
 brew install cmake openblas llvm
 
 # configure
 cmake -B build -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++  -DFAISS_ENABLE_C_API=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release -DFAISS_ENABLE_GPU=OFF -DFAISS_ENABLE_PYTHON=OFF -DBUILD_TESTING=OFF
 
 # compile
 cmake --build build --config Release
 
 # install
 cmake --install build --prefix=$HOME/faiss
 cp build/c_api/libfaiss_c.dylib $HOME/faiss/lib/
```

## `Linux`

`gcc`, `cmake`, [`intelmkl`](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html), `cuda` needed, install in advance.

```shell
# configure
cmake -B build -DFAISS_ENABLE_C_API=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release -DFAISS_ENABLE_GPU=ON -DFAISS_ENABLE_PYTHON=OFF -DBUILD_TESTING=OFF

# compile
 cmake --build build --config Release

# install
 cmake --install build --prefix=$HOME/faiss
 cp build/c_api/libfaiss_c.so $HOME/faiss/lib/
```
## `Windows`
`Visual Studio 2022`, `cmake`, [`intelmkl`](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html), `cuda` needed, install in advance.

```shell
# configure
cmake -B build -DFAISS_ENABLE_C_API=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release -DFAISS_ENABLE_GPU=ON -DFAISS_ENABLE_PYTHON=OFF -DBUILD_TESTING=OFF

# compile
 cmake --build build --config Release

# install
cmake --install build --prefix=%USERPROFILE%\faiss
copy build\c_api\Release\faiss_c.dll %USERPROFILE%\faiss\bin
copy build\c_api\Release\faiss_c.lib %USERPROFILE%\faiss\lib\
```

## Bindings

Bindings was generated by running the follow commands under `faiss-next-sys` folder
```shell
cargo build --features bindgen
```
or, generate bindings with `gpu` enabled 
```shell
cargo build --features bindgen,gpu
```

Generated bindings looks like:

```shell
└── src
    ├── lib.rs
    ├── linux
    │   ├── bindings.rs      #linux cpu bindings
    │   └── bindings_gpu.rs  #linux gpu bindings
    ├── macos
    │   └── bindings.rs      #macos cpu bindings, gpu is not supported
    └── windows
        ├── bindings.rs	     #windows cpu bindings 
        └── bindings_gpu.rs  #windows gpu bindings
```