Environment:Online ml River Build Toolchain

Knowledge Sources	River setuptools-rust
Domains	Infrastructure, Build_System
Last Updated	2026-02-08 16:00 GMT

Overview

Build toolchain requiring Cython, C++11 compiler, and Rust 2021 edition for compiling River from source.

Description

This environment provides the compilation toolchain required to build River from source. River includes performance-critical components written in Cython (`.pyx` files for ADWIN drift detection, vectorized dictionaries, ROC AUC computation, and expected mutual information), C++ (rolling ROC AUC), and Rust (streaming statistics via PyO3). Pre-built wheels bypass these requirements, but source builds (e.g., development or custom platforms) require the full toolchain.

Usage

This environment is required only when building River from source. This includes development workflows, contributing to River, building for unsupported platforms, or modifying Cython/Rust extensions. Users installing via `pip install river` from PyPI with available pre-built wheels do not need this environment.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Windows excludes `-lm` math library link
C++ Compiler	C++11 support	gcc, clang, or MSVC; required for Cython and C++ extensions
Rust Toolchain	Rust 2021 edition	For PyO3 bindings; install via `rustup`
Python	>= 3.11	Same as runtime requirement
Disk	~500MB	Compiler toolchain, Rust target, build artifacts

Dependencies

System Packages

C++11-capable compiler (`gcc >= 4.8`, `clang >= 3.3`, or MSVC 2015+)
Rust toolchain (install via `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)

Python Build Packages

`Cython` — Compiles `.pyx` files to C/C++ extensions
`numpy` — Required at build time for `numpy.get_include()` header path
`setuptools` — Standard Python packaging
`setuptools-rust` — Builds Rust extensions via `RustExtension`

Rust Dependencies (Cargo.toml)

`pyo3` = 0.23.1 (Python-Rust bindings)
`watermill` = 0.1.1 (streaming statistics)
`bincode` = 1.3.3 (serialization)
`serde` = 1.0 (serialization framework)

Credentials

No credentials required for building from source.

Quick Install

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install Python build dependencies
pip install Cython numpy setuptools setuptools-rust

# Build River from source
git clone https://github.com/online-ml/river.git
cd river
pip install -e .

Code Evidence

Build configuration from `setup.py:12-26`:

ext_modules = cythonize(
    module_list=[
        setuptools.Extension(
            "*",
            sources=["river/**/*.pyx"],
            include_dirs=[numpy.get_include()],
            libraries=[] if platform.system() == "Windows" else ["m"],
            define_macros=[("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")],
        )
    ],
    compiler_directives={
        "binding": True,
        "embedsignature": True,
    },
)

Rust extension definition from `setup.py:28`:

rust_extensions = [RustExtension("river.stats._rust_stats", binding=Binding.PyO3)]

Build failure handling from `setup.py:35-46`:

class ExtBuilder(build_ext):
    def run(self):
        try:
            build_ext.run(self)
        except FileNotFoundError:
            raise BuildFailed("File not found. Could not compile C extension.")

    def build_extension(self, ext):
        try:
            build_ext.build_extension(self, ext)
        except (CCompilerError, ValueError):
            raise BuildFailed("Could not compile C extension.")

Rust Cargo.toml dependencies from `Cargo.toml:13-17`:

[dependencies]
pyo3 = { version = "0.23.1", features = ["extension-module"] }
watermill = "0.1.1"
bincode = "1.3.3"
serde = { version = "1.0", features = ["derive"] }

Common Errors

Error Message	Cause	Solution
`BuildFailed: File not found. Could not compile C extension.`	Missing C/C++ compiler	Install `gcc` or `clang` via system package manager
`BuildFailed: Could not compile C extension.`	Compiler error in Cython files	Ensure C++11 support; update compiler if needed
`error: can't find Rust compiler`	Rust not installed	sh`
`ModuleNotFoundError: No module named 'Cython'`	Cython not installed	`pip install Cython`

Compatibility Notes

Windows: The math library (`-lm`) is excluded from the link step on Windows (`libraries=[] if platform.system() == "Windows" else ["m"]`).
Cython Optimization Directives: Extensions are compiled with `boundscheck=False`, `cdivision=True`, and `wraparound=False` for maximum performance. These are safe for River's internal usage patterns.
NumPy API: Build uses `NPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION` to suppress NumPy deprecation warnings and ensure forward compatibility.
Pre-built Wheels: Available for most common platforms (Linux x86_64, macOS, Windows). This environment is only needed if no wheel is available for your platform.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment