Implementation:Rapidsai Cuml Build Script

Knowledge Sources	Rapidsai_Cuml
Domains	Machine_Learning, Build_System
Last Updated	2026-02-08 12:00 GMT

Overview

The top-level build script for the cuML project that orchestrates CMake-based C++ builds and pip-based Python builds with extensive configuration options.

Description

build.sh is the primary entry point for building cuML from source. It supports building multiple targets including the C++ library (libcuml), the Python package (cuml), ML primitives tests (prims), benchmarks (bench, prims-bench), multi-GPU tests (cpp-mgtests), and documentation (cppdocs, pydocs).

The script performs the following stages:

1. Argument Parsing -- Validates targets and flags against a known list. Supports both short flags (-v, -g, -n) and long flags (--allgpuarch, --singlegpu, --ccache, etc.).
2. Clean -- When the clean target is specified, removes all build directories, Python artifacts, and cache files.
3. CMake Configuration -- Configures the C++ build using CMake with options for CUDA architectures (native or all supported), build type (Release or RelWithDebInfo), tests, MPI communications, NVTX profiling, ccache, and Treelite static linking.
4. C++ Compilation -- Builds the C++ targets using CMake with Ninja as the default generator, supporting parallel compilation via PARALLEL_LEVEL.
5. Build Metrics -- Optionally generates an HTML build metrics report from the Ninja log, including sccache/ccache hit rates and library sizes.
6. Python Installation -- Installs the Python package using pip install with scikit-build-core and optional arguments for single-GPU mode, code coverage, and stable ABI.

Key environment variables include PARALLEL_LEVEL (compilation threads), CUML_EXTRA_CMAKE_ARGS (additional CMake arguments), and CUML_EXTRA_PYTHON_ARGS (additional pip arguments).

Usage

Use this script when building cuML from source for development, testing, or packaging. The default invocation (no arguments) builds and installs libcuml, cuml, and prims for the detected GPU architecture.

Code Reference

Source Location

• Repository: Rapidsai_Cuml
• File: build.sh

Signature

#!/bin/bash
# build.sh [<target> ...] [<flag> ...]
# Targets: clean libcuml cuml cpp-mgtests prims bench prims-bench cppdocs pydocs
# Flags: -v -g -n --allgpuarch --singlegpu --nolibcumltest --nvtx
#        --show_depr_warn --codecov --ccache --configure-only
#        --build-metrics --incl-cache-stats

Import

# Run from the repository root:
./build.sh [targets] [flags]

I/O Contract

Inputs

Name	Type	Required	Description
targets	String(s)	No	One or more build targets: clean, libcuml, cuml, cpp-mgtests, prims, bench, prims-bench, cppdocs, pydocs
-v / --verbose	Flag	No	Enable verbose build output
-g / --debug	Flag	No	Build in RelWithDebInfo mode
-n / --no-install	Flag	No	Skip the install step
--allgpuarch	Flag	No	Build for all supported GPU architectures (RAPIDS set)
--singlegpu	Flag	No	Disable multi-GPU components
--nolibcumltest	Flag	No	Disable building C++ tests
--ccache	Flag	No	Enable ccache for compilation caching
PARALLEL_LEVEL	Env var	No	Number of parallel compilation threads (default: nproc)
CUML_EXTRA_CMAKE_ARGS	Env var	No	Extra CMake arguments passed to the C++ build

Outputs

Name	Type	Description
libcuml++.so	Shared library	The compiled cuML C++ library
cuml Python package	Installed package	The cuML Python package installed into the active environment
ninja_log.html	HTML report	Build metrics report (when --build-metrics is used)

Usage Examples

# Default build (libcuml + cuml + prims for native GPU arch)
./build.sh

# Build only C++ library in debug mode with verbose output
./build.sh libcuml -g -v

# Build everything for all GPU architectures with ccache
./build.sh --allgpuarch --ccache

# Clean all build artifacts
./build.sh clean

# Build only Python package
./build.sh cuml

# Build with custom CMake args
CUML_EXTRA_CMAKE_ARGS="-DBUILD_CUML_C_LIBRARY=OFF" ./build.sh libcuml

Related Pages

• Environment:Rapidsai_Cuml_CUDA_GPU