Rust Build Script

Purpose

The Rust Build Script (`build.rs`) orchestrates the conditional compilation and environment setup for the Rust components of the project. It addresses the need to:

Detect and verify the Python implementation and version the project is being built against.
Enable or disable optional Rust features based on compiler capabilities, platform architecture, and user environment variables.
Compile the embedded yyjson C library with custom configuration flags, ensuring seamless integration and maximum performance.
Prevent incompatible or conflicting build configurations early in the build process.

This script is essential for tailoring the Rust build to the target environment, improving portability and robustness while providing fine-grained control over feature toggling.

Functionality

The build script performs the following core workflows:

Change and Environment Monitoring
It instructs Cargo to rerun the build script if critical files or environment variables change:
```
println!("cargo:rerun-if-changed=build.rs");
println!("cargo:rerun-if-env-changed=ORJSON_DISABLE_YYJSON");
```
This ensures the build adapts dynamically to code or environment modifications.

Python Implementation Detection
Using pyo3_build_config, the script queries the Python interpreter configuration:

let python_config = pyo3_build_config::get();
if python_config.implementation == pyo3_build_config::PythonImplementation::CPython {
    println!("cargo:rustc-cfg=CPython");
} else {
    panic!("orjson only supports CPython")
}

This guarantees compatibility by restricting builds to CPython only.

Conditional Compilation Flags Based on Environment and Compiler Features
It conditionally enables Rust features such as avx512 SIMD instructions, core intrinsics, optimization attributes, and inline integer optimizations depending on platform and compiler support:

if version_check::supports_feature("core_intrinsics").unwrap_or(false) {
    println!("cargo:rustc-cfg=feature=\"intrinsics\"");
}
if version_check::supports_feature("optimize_attribute").unwrap_or(false) {
    println!("cargo:rustc-cfg=feature=\"optimize\"");
}

Embedded yyjson Compilation with Safety Checks
The script compiles the embedded yyjson C source with several disabled features for performance and compliance:
```
cc::Build::new()
    .file("include/yyjson/yyjson.c")
    .include("include/yyjson")
    .define("YYJSON_DISABLE_NON_STANDARD", "1")
    .define("YYJSON_DISABLE_UTF8_VALIDATION", "1")
    .define("YYJSON_DISABLE_UTILS", "1")
    .define("YYJSON_DISABLE_WRITER", "1")
    .try_compile("yyjson")
```
It also enforces mutual exclusivity between disabling yyjson through environment variables and enabling it via Cargo features, preventing ambiguous builds.
Python Version Feature Flags
The script emits Rust configuration flags for specific Python versions detected, enabling version-targeted conditional compilation in the Rust source:
```
println!("cargo:rustc-check-cfg=cfg(Py_3_10)");
println!("cargo:rustc-check-cfg=cfg(Py_3_11)");
// and so forth...
```

Relationship to the Parent Topic

The Rust Build Script is a critical subcomponent within the broader **Build Configuration and Compilation** topic. While the parent topic covers general build system setup and CI configurations, this subtopic provides the detailed logic for:

Dynamically configuring Rust compilation flags based on environment and Python interpreter.
Integrating the embedded C library (yyjson) compilation seamlessly into the Rust build.
Enforcing build-time constraints and dependencies that ensure the correctness and performance of the Rust core.

This fine-grained control complements other build scripts and manifests by handling low-level compiler and environment adaptations specific to Rust and Python interoperability, which is not covered by higher-level build or CI scripts.

Diagram

Build Script Workflow Flowchart

flowchart TD
    Start[Start build.rs execution]
    CheckChanges[Check changed files/env variables]
    DetectPython[Detect Python implementation and version]
    VerifyCPython{Is CPython?}
    SetupRustFlags[Setup Rust cfg flags for features and Python version]
    CheckEnvVars[Check ORJSON_DISABLE_YYJSON and Cargo features]
    CompileYYJSON{Compile yyjson C library?}
    Success[Emit feature flags and finish]
    PanicBuild[Abort build with error]

    Start --> CheckChanges --> DetectPython --> VerifyCPython
    VerifyCPython -- Yes --> SetupRustFlags --> CheckEnvVars --> CompileYYJSON
    VerifyCPython -- No --> PanicBuild
    CheckEnvVars -- Conflict --> PanicBuild
    CompileYYJSON -- Success --> Success
    CompileYYJSON -- Fail & feature enabled --> PanicBuild
    CompileYYJSON -- Fail & feature disabled --> Success

This flowchart visualizes the core decision points and actions performed during the build script execution, emphasizing environment detection, feature gating, and conditional compilation steps.