Installation

The cuVS software development kit provides APIs for C, C++, Python, and Rust languages. This guide outlines how to install the pre-compiled packages, build it from source, and use it in downstream applications.

• Installing pre-compiled packages

  • C, C++, and Python through Conda

  • Python through Pip

  • Rust through crates.io

• Build from source

  • Prerequisites

  • Create a build environment

  • C and C++ Libraries

    • Building the Googletests

  • Python Library

  • Rust Library

  • Using Cmake Directly

• Build Documentation

Installing Pre-compiled Packages

C, C++, and Python through Conda

The easiest way to install the pre-compiled C, C++, and Python packages is through conda. Use the following commands, depending on your CUDA version, to install cuVS packages (replace rapidsai with rapidsai-nightly to install more up-to-date but less stable nightly packages). mamba is preferred over the conda command.

C++ Package

mamba install -c rapidsai -c conda-forge -c nvidia libcuvs cuda-version=12.0

C Package

mamba install -c rapidsai -c conda-forge -c nvidia libcuvs_c cuda-version=12.0

Python Package

mamba install -c rapidsai -c conda-forge -c nvidia cuvs cuda-version=12.0

Python through Pip

The cuVS Python package can also be installed through pip.

For CUDA 11 packages:

pip install cuvs-cu11 --extra-index-url=https://pypi.nvidia.com

And CUDA 12 packages:

pip install cuvs-cu12 --extra-index-url=https://pypi.nvidia.com

Note: these packages statically link the C and C++ libraries so the libcuvs and libcuvs_c shared libraries won’t be readily available to use in your code.

Rust through crates.io

Build from source

The core cuVS source code is written in C++ and wrapped through a C API. The C API is wrapped around the C++ APIs and the other supported languages are built around the C API.

Prerequisites

• Cmake 3.26.4+

• GCC 9.3+ (11.4+ recommended)

• CUDA Toolkit 11.4+

• Volta architecture or better (compute capability >= 7.0)

Create a build environment

Conda environment scripts are provided for installing the necessary dependencies to build cuVS from source. It is preferred to use mamba, as it provides significant speedup over conda:

mamba env create --name cuvs -f conda/environments/all_cuda-120_arch-x86_64.yaml
mamba activate cuvs

The process for building from source with CUDA 11 differs slightly in that your host system will also need to have CUDA toolkit installed which is greater than, or equal to, the version you install into you conda environment. Installing CUDA toolkit into your host system is necessary because nvcc is not provided with Conda’s cudatoolkit dependencies for CUDA 11. The following example will install create and install dependencies for a CUDA 11.8 conda environment

mamba env create --name cuvs -f conda/environments/all_cuda-118_arch-x86_64.yaml
mamba activate cuvs

The recommended way to build and install cuVS from source is to use the build.sh script in the root of the repository. This script can build both the C++ and Python artifacts and provides CMake options for building and installing the headers, tests, benchmarks, and the pre-compiled shared library.

C and C++ libraries

The C and C++ shared libraries are built together using the following arguments to build.sh:

./build.sh libcuvs

In above example the libcuvs.so and libcuvs_c.so shared libraries are installed by default into $INSTALL_PREFIX/lib. To disable this, pass -n flag.

Once installed, the shared libraries, headers (and any dependencies downloaded and installed via rapids-cmake) can be uninstalled using build.sh:

./build.sh libcuvs --uninstall

Building the Googletests

Compile the C and C++ Googletests using the tests target in build.sh.

./build.sh libcuvs tests

The tests will be written to the build directory, which is cpp/build/ by default, and they will be named *_TEST.

It can take some time to compile all of the tests. You can build individual tests by providing a semicolon-separated list to the --limit-tests option in build.sh. Make sure to pass the -n flag so the tests are not installed.

./build.sh libcuvs tests -n --limit-tests=NEIGHBORS_TEST;CAGRA_C_TEST

Python library

The Python library should be built and installed using the build.sh script:

./build.sh python

The Python packages can also be uninstalled using the build.sh script:

./build.sh python --uninstall

Rust library

The Rust bindings can be built with

./build.sh rust

Using CMake directly

When building cuVS from source, the build.sh script offers a nice wrapper around the cmake commands to ease the burdens of manually configuring the various available cmake options. When more fine-grained control over the CMake configuration is desired, the cmake command can be invoked directly as the below example demonstrates.

The CMAKE_INSTALL_PREFIX installs cuVS into a specific location. The example below installs cuVS into the current Conda environment:

cd cpp
mkdir build
cd build
cmake -D BUILD_TESTS=ON -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX ../
make -j<parallel_level> install

cuVS has the following configurable cmake flags available:

Cmake Flags

Flag	Possible Values	Default Value	Behavior
BUILD_TESTS	ON, OFF	ON	Compile Googletests
CUDA_ENABLE_KERNELINFO	ON, OFF	OFF	Enables kernelinfo in nvcc. This is useful for compute-sanitizer
CUDA_ENABLE_LINEINFO	ON, OFF	OFF	Enable the -lineinfo option for nvcc
CUDA_STATIC_RUNTIME	ON, OFF	OFF	Statically link the CUDA runtime
DETECT_CONDA_ENV	ON, OFF	ON	Enable detection of conda environment for dependencies
CUVS_NVTX	ON, OFF	OFF	Enable NVTX markers

Build documentation

The documentation requires that the C, C++ and Python libraries have been built and installed. The following will build the docs along with the necessary libraries:

./build.sh libcuvs python docs