Building from the source#

Setting up your build environment#

Please see the Installation Guide for NVIDIA CUDA-X libraries for data science for information about supported operating systems, GPU drivers, and CUDA versions.

Note

Building nvForest without GPU support

It is possible to build nvForest without GPU support; in this case, the CUDA toolkit is not required. To build nvForest without GPU, set the CMake option NVFOREST_ENABLE_GPU=OFF.

Using Conda to install all software dependencies#

We highly recommend the use of Conda, a package manager that lets you obtain all necessary software dependencies in a virtual environment. We provide environment definition files conda/environments/all_*.yaml containing all software dependencies for nvForest.

To create a development environment named nvforest_dev, use the following commands.

$ conda create -n nvforest_dev python=3.13
$ conda env update -n nvforest_dev \
    --file=conda/environments/all_cuda-134_arch-$(uname -m).yaml
$ conda activate nvforest_dev

Installing from Source#

Option 1. Use the convenience wrapper script (Recommended)#

As a convenience, a build.sh script is provided to simplify the build process. The libraries will be installed to $INSTALL_PREFIX if set (e.g., export INSTALL_PREFIX=/install/path); otherwise it will be installed to $CONDA_PREFIX.

# Build the nvForest libraries, tests, and python package, then
# Install them to $INSTALL_PREFIX if set, otherwise $CONDA_PREFIX
./build.sh

For workflows that involve frequent switching among branches or between debug and release builds, it is recommended that you install ccache and make use of it by passing the --ccache flag to build.sh.

To build individual components, specify them as arguments to build.sh:

# Build and install the nvForest C++ and C-wrapper libraries
./build.sh libnvforest

# Build and install the nvForest Python package
./build.sh nvforest

Other build.sh options:

# Remove any prior build artifacts and configuration (start over)
./build.sh clean

# Build and install libnvforest with verbose output
./build.sh libnvforest -v

# Build and install libnvforest for debug
./build.sh libnvforest -g

# Build and install libnvforest limiting parallel build jobs to 8 (ninja -j8)
PARALLEL_LEVEL=8 ./build.sh libnvforest

# Build libnvforest but do not install
./build.sh libnvforest -n

# Use ccache to cache compilations, speeding up subsequent builds
./build.sh --ccache

By default, Ninja is used as the cmake generator. To override this and use, e.g., GNU Make, define the CMAKE_GENERATOR environment variable accordingly:

CMAKE_GENERATOR='Unix Makefiles' ./build.sh

To run the C++ unit tests (optional), from the repo root:

ctest --test-dir cpp/build

If you want a list of the available C++ tests:

ctest -N --test-dir cpp/build

To run all Python tests, from the repo root:

pytest -v python/nvforest/tests

If you want a list of the available Python tests:

pytest -v python/nvforest/tests --collect-only

Option 2. Manually invoke CMake and build toolchain#

Once dependencies are present, follow the steps below:

Clone the repository:

git clone https://github.com/rapidsai/nvforest.git

Build and install libnvforest (C++/CUDA library containing the nvForest algorithms), starting from the repository root folder:

mkdir cpp/build
cmake -B cpp/build -S cpp/ -GNinja

Note

If CUDA is not in your PATH, you may need to set CUDA_BIN_PATH before running CMake:

export CUDA_BIN_PATH=$CUDA_HOME  # Default: /usr/local/cuda

If using a Conda environment (recommended), configure CMake to install libnvforest into the Conda environment:

cmake -B cpp/build -S cpp/ -GNinja -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX

Note

You may see the following warning depending on your cmake version and CMAKE_INSTALL_PREFIX. This warning can be safely ignored:

Cannot generate a safe runtime search path for target ml_test because files
in some directories may conflict with libraries in implicit directories:

To silence it, add -DCMAKE_IGNORE_PATH=$CONDA_PREFIX/lib to your cmake command.

To reduce compile times, you can specify GPU compute capabilities to compile for. For example, for Volta GPUs:

cmake -B cpp/build -S cpp/ -GNinja -DCMAKE_CUDA_ARCHITECTURES="70"

Or for multiple architectures (e.g., Ampere and Hopper):

cmake -B cpp/build -S cpp/ -GNinja -DCMAKE_CUDA_ARCHITECTURES="80;86;90"

You may also wish to make use of ccache to reduce build times when switching among branches or between debug and release builds:

cmake -B cpp/build -S cpp/ -GNinja -DUSE_CCACHE=ON

There are many options to configure the build process, see the Custom Build Options section.

Build libnvforest:

cmake --build cpp/build --target all -v
cmake --build cpp/build --target install -v

To run tests (optional):

ctest --test-dir cpp/build

To build doxygen docs for all C/C++ source files:

cmake --build cpp/build --target docs_nvforest

Build and install the nvforest python package.

From the repository root:

python -m pip install --no-build-isolation --no-deps \
  --config-settings rapidsai.disable-cuda=true python/nvforest

To run Python tests (optional):

pytest -v python/nvforest/tests

If you want a list of the available tests:

pytest -v python/nvforest/tests --collect-only

Building the Documentation#

The documentation build requires nvforest to be installed, since Sphinx imports it to generate the Python API reference. Build and install it first using one of the options above. The tools needed to build the documentation (Sphinx, Doxygen, etc.) are included in the conda/environments/all_*.yaml environment files.

1. Generate the Doxygen XML for the C++ API reference. This step is always required before the first documentation build, since neither make html nor sphinx-build runs Doxygen. Afterwards, it only needs to be re-run when the C++ headers change. From the repository root:

(cd cpp/doxygen && doxygen Doxyfile.in)

Build the HTML documentation from the docs directory:

cd docs
make html

The output is written to docs/build/html. Open docs/build/html/index.html in your browser to view it.

Tip

If you are building on a remote machine, serve the output with python -m http.server -d build/html 8000 and forward port 8000 to your local machine (e.g., ssh -L 8000:localhost:8000 <remote-host>, or the Ports panel in VS Code Remote-SSH). Then open http://localhost:8000 in your browser.

3. Before opening a pull request, check that the documentation builds as it does in CI (see ci/build_docs.sh). From the docs directory:

# Build the HTML documentation, treating warnings as errors
sphinx-build -b dirhtml ./source _html -W

# Run the code examples in the documentation as tests
sphinx-build --builder doctest ./source _doctest -W

Unlike make html, these commands use -W to turn warnings into errors, so they catch issues that would fail CI. The dirhtml builder generates a <page>/index.html layout, so to view its output, serve the directory and open http://localhost:8000 in your browser:

python -m http.server -d _html 8000

Live preview with sphinx-autobuild#

When editing the documentation, sphinx-autobuild rebuilds the docs whenever a file changes and refreshes the page in your browser automatically. Install it into your development environment:

conda install -c conda-forge sphinx-autobuild

Then, from the docs directory:

sphinx-autobuild ./source _autobuild --port 8000

and open http://localhost:8000 in your browser. By default, only files under source are watched. To also rebuild when Python docstrings change, add --watch ../python/nvforest. Note that docstring changes only take effect if Sphinx imports the modified code, so nvforest must be installed in editable mode or reinstalled after each change.

Tip

If you are building on a remote machine, either forward the port over SSH (e.g., ssh -L 8000:localhost:8000 <remote-host>) or pass --host 0.0.0.0 to sphinx-autobuild.

Custom Build Options#

libnvforest#

nvForest’s cmake has the following configurable flags available:

Flag	Possible Values	Default Value	Behavior
NVFOREST_ENABLE_GPU	[ON, OFF]	ON	Enable/disable GPU support
BUILD_SHARED_LIBS	[ON, OFF]	ON	Whether to build libnvforest as a shared library
BUILD_NVFOREST_TESTS	[ON, OFF]	ON	Enable/disable building nvForest C++ test executables
CUDA_ENABLE_KERNEL_INFO	[ON, OFF]	OFF	Enable/disable kernel resource usage info in nvcc.
CUDA_ENABLE_LINE_INFO	[ON, OFF]	OFF	Enable/disable lineinfo in nvcc.
DETECT_CONDA_ENV	[ON, OFF]	ON	Use detection of conda environment for dependencies. If set to ON, and no value for CMAKE_INSTALL_PREFIX is passed, then it will assign it to $CONDA_PREFIX (to install in the active environment).
DISABLE_DEPRECATION_WARNINGS	[ON, OFF]	ON	Set to ON to disable deprecation warnings
DISABLE_OPENMP	[ON, OFF]	OFF	Set to ON to disable OpenMP
NVTX	[ON, OFF]	OFF	Enable/disable nvtx markers in libnvforest.
USE_CCACHE	[ON, OFF]	OFF	Whether to cache build artifacts with ccache.
NVFOREST_USE_TREELITE_STATIC	[ON, OFF]	OFF	Whether to statically link the Treelite library.
NVFOREST_EXPORT_TREELITE_LINKAGE	[ON, OFF]	OFF	Whether to publicly link Treelite to libnvforest
CUDA_WARNINGS_AS_ERRORS	[ON, OFF]	ON	Treat all warnings from CUDA as errors
CMAKE_CUDA_ARCHITECTURES	List of GPU architectures, semicolon-separated	Empty	List the GPU architectures to compile the GPU targets for. Set to “NATIVE” to auto detect GPU architecture of the system, set to “ALL” to compile for all supported archs.