Build and Development Scripts

Purpose

This subtopic addresses the automation and standardization of building, testing, linting, and deploying the project artifacts. While the parent topic covers the overall build configuration and compilation setup for Rust and C integration, these scripts provide practical, easy-to-use command-line tools to streamline developer workflows. They ensure consistent environment settings, compiler flags, dependency management, and quality checks, reducing manual errors and speeding up development cycles.

Functionality

The build and development scripts encapsulate key workflows such as compiling Rust code into Python extension wheels, running tests, enforcing code style, and preparing packages for distribution. Each script is focused on a distinct stage of the development lifecycle:

script/cargo: A lightweight wrapper around the cargo build tool that sets environment variables to optimize PyO3 builds and enforce panic behavior during compilation. It forwards arguments directly to cargo while controlling the target platform.
script/debug: Cleans previous build artifacts and wheels, configures environment variables for debug-friendly compilation flags (e.g., unwinding panics), builds the Python wheel with maturin in development mode, installs the wheel, runs the test suite, and sets up Cargo configuration files for incremental builds.
script/develop: Similar to debug but tuned for release or optimized builds with linker plugin LTO and LLVM emission flags. It cleans wheels, builds with maturin using the specified target, installs the wheel with pip, and prints compiler/linker environment information for debugging.
script/lint: Runs static analysis and formatting tools on key Python source files and scripts. It uses ruff for linting and auto-fixes, and mypy for type checking, ensuring code style and correctness before commits or CI runs.

These scripts share common environment variable exports to enforce consistent compiler/linker settings and PyO3 build behaviors, like:

export UNSAFE_PYO3_BUILD_FREE_THREADED=1
export UNSAFE_PYO3_SKIP_VERSION_CHECK=1

This helps bypass known PyO3 threading and version checks safely for improved build parallelism and compatibility.

Integration

These development scripts complement the parent topic of build configuration by providing practical entry points for developers to invoke the complex Rust build system and Python packaging without manually handling low-level flags or environment variables. They rely on the `build.rs` and `Cargo.toml` definitions from the parent topic to determine compilation features and dependencies.

Moreover, these scripts integrate tightly with the Python packaging tool `maturin`, which bridges Rust crates to Python wheels, and with Python testing (`pytest`) and linting (`ruff`, `mypy`) tools. This creates a seamless workflow from code changes to validated, distributable Python packages.

By encapsulating environment setup, compilation flags, build invocation, installation, and testing, these scripts reduce cognitive load and errors for developers, ensuring builds and tests run reproducibly across machines and CI systems.

Example snippet from `script/debug` showing build and test workflow:

maturin build --profile=dev --target=${TARGET} --features="${ORJSON_FEATURES}" --interpreter "${PYTHON}"
uv pip install ${CARGO_TARGET_DIR}/wheels/*.whl
pytest -v test

This sequence builds the wheel with debug features, installs it, and runs tests, all automatically.

Diagram

flowchart TD
    Clean[Clean Build Artifacts]
    SetupEnv[Set Environment Variables]
    Build[Invoke Build: cargo/maturin]
    Install[Install Python Wheel]
    Test[Run Test Suite]
    Lint[Run Lint and Type Checks]

    Clean --> SetupEnv --> Build --> Install --> Test
    SetupEnv --> Lint