# Building from the source ## Setting up your build environment Please see the [Installation Guide](https://docs.nvidia.com/datascience/install/#system-requirements) 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. ```console $ 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`. ```bash # 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](https://ccache.dev/) and make use of it by passing the `--ccache` flag to `build.sh`. To build individual components, specify them as arguments to `build.sh`: ```bash # 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: ```bash # 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: ```bash CMAKE_GENERATOR='Unix Makefiles' ./build.sh ``` To run the C++ unit tests (optional), from the repo root: ```bash ctest --test-dir cpp/build ``` If you want a list of the available C++ tests: ```bash ctest -N --test-dir cpp/build ``` To run all Python tests, from the repo root: ```bash pytest -v python/nvforest/tests ``` If you want a list of the available Python tests: ```bash pytest -v python/nvforest/tests --collect-only ``` ### Option 2. Manually invoke CMake and build toolchain Once dependencies are present, follow the steps below: 1. Clone the repository: ```bash git clone https://github.com/rapidsai/nvforest.git ``` 1. Build and install `libnvforest` (C++/CUDA library containing the nvForest algorithms), starting from the repository root folder: ```bash 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: ```bash 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: ```bash 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: ```default 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: ```bash cmake -B cpp/build -S cpp/ -GNinja -DCMAKE_CUDA_ARCHITECTURES="70" ``` Or for multiple architectures (e.g., Ampere and Hopper): ```bash 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: ```bash cmake -B cpp/build -S cpp/ -GNinja -DUSE_CCACHE=ON ``` There are many options to configure the build process, see the [Custom Build Options](#custom-build-options) section. 1. Build `libnvforest`: ```bash cmake --build cpp/build --target all -v cmake --build cpp/build --target install -v ``` To run tests (optional): ```bash ctest --test-dir cpp/build ``` To build doxygen docs for all C/C++ source files: ```bash cmake --build cpp/build --target docs_nvforest ``` 1. Build and install the `nvforest` python package. From the repository root: ```bash python -m pip install --no-build-isolation --no-deps \ --config-settings rapidsai.disable-cuda=true python/nvforest ``` To run Python tests (optional): ```bash pytest -v python/nvforest/tests ``` If you want a list of the available tests: ```bash 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: ```bash (cd cpp/doxygen && doxygen Doxyfile.in) ``` 1. Build the HTML documentation from the `docs` directory: ```bash 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 `, or the Ports panel in VS Code Remote-SSH). Then open [http://localhost:8000](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: ```bash # 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 `/index.html` layout, so to view its output, serve the directory and open [http://localhost:8000](http://localhost:8000) in your browser: ```bash python -m http.server -d _html 8000 ``` ### Live preview with sphinx-autobuild When editing the documentation, [sphinx-autobuild](https://github.com/sphinx-doc/sphinx-autobuild) rebuilds the docs whenever a file changes and refreshes the page in your browser automatically. Install it into your development environment: ```bash conda install -c conda-forge sphinx-autobuild ``` Then, from the `docs` directory: ```bash sphinx-autobuild ./source _autobuild --port 8000 ``` and open [http://localhost:8000](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 `) 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. |