Implementation:Nautechsystems Nautilus trader Build Script
| Knowledge Sources | |
|---|---|
| Domains | Build_Tooling, Python, Rust |
| Last Updated | 2026-02-10 08:00 GMT |
Overview
Python build script that orchestrates the two-phase compilation of Rust static libraries and Cython extension modules into a single installable Python package.
Description
The build.py script is the critical build glue between the Rust and Python/Cython layers of NautilusTrader. It executes a two-phase build: (1) Rust compilation invokes cargo build with configurable feature flags (high-precision, ffi, python, postgres, cython-compat, extension-module, tracing-bridge), copies static libraries (nautilus_backtest, nautilus_common, nautilus_core, nautilus_model, nautilus_persistence) and the PyO3 dynamic library to the appropriate locations. (2) Cython compilation discovers all .pyx files, generates C extension modules via Cython, and links them against the Rust static libraries.
The script handles platform-specific compiler/linker flags: clang on Linux, dynamic_lookup on macOS, MSVC library linking on Windows, ARM64 cross-compilation flags, and sccache integration. It is configurable via environment variables: BUILD_MODE (release/debug/debug-pyo3), HIGH_PRECISION (128-bit integer support), PROFILE_MODE, ANNOTATION_MODE, PARALLEL_BUILD, PYO3_ONLY (skip Cython to reduce compile time), COPY_TO_SOURCE, FORCE_STRIP, and DRY_RUN.
Usage
This script is invoked automatically by the poetry-core build backend (configured in pyproject.toml) during pip install or pip install -e . for the v1 package. It can also be run directly for development builds.
Code Reference
Source Location
- Repository: Nautechsystems_Nautilus_trader
- File: build.py
- Lines: 1-616
Signature
# Key functions:
def _set_feature_flags() -> list[str]:
"""Configure Cargo feature flags based on HIGH_PRECISION setting."""
def _build_rust_libs() -> None:
"""Compile Rust crates via cargo build with configured features and profile."""
def build() -> list[Extension]:
"""Main entry point: build Rust libs, discover .pyx files, return Extension list."""
# Key constants:
BUILD_MODE: str # "release" | "debug" | "debug-pyo3"
HIGH_PRECISION: bool # Enable 128-bit integer precision
PARALLEL_BUILD: bool # Use all CPUs for Cython compile stage
PYO3_ONLY: bool # Skip Cython extensions, only build PyO3
COPY_TO_SOURCE: bool # Copy .so files into source tree
Import
# Called by setuptools via pyproject.toml build-system configuration
# Direct invocation:
from build import build
extensions = build()
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| BUILD_MODE | EnvVar | No | Build profile: release, debug, or debug-pyo3 (default: release) |
| HIGH_PRECISION | EnvVar | No | Enable 128-bit integer precision (default: true) |
| PYO3_ONLY | EnvVar | No | Skip Cython, build only PyO3 extension |
| PARALLEL_BUILD | EnvVar | No | Use all CPUs for Cython compile (default: true) |
| .pyx files | Files | Yes | Cython source files under nautilus_trader/ |
| Cargo.toml | File | Yes | Workspace manifest for Rust compilation |
Outputs
| Name | Type | Description |
|---|---|---|
| Static libraries | .a/.lib files | Rust static libraries copied to target directory |
| PyO3 library | .so/.dylib/.dll | Python extension module from Rust PyO3 crate |
| Cython extensions | .so/.pyd files | Compiled Cython C extension modules |
Usage Examples
# Standard development build (release mode, high precision)
pip install -e .
# Debug build for development
BUILD_MODE=debug pip install -e .
# PyO3 only (faster iteration when not changing Cython code)
PYO3_ONLY=1 pip install -e .
# Standard precision on Windows (128-bit not supported)
HIGH_PRECISION=false pip install -e .
# Profile mode for coverage/profiling
PROFILE_MODE=1 pip install -e .
# Dry run to see commands without executing
DRY_RUN=1 python build.py