How to Build and Compile Headroom: Complete Guide to Rust Extensions and Native Binaries

Headroom requires building a Rust extension and optional native proxy binary using Make, Maturin, and Cargo, though pre-built wheels on PyPI allow pure-Python installation without compilation.

The chopratejas/headroom repository is a mixed-language project that combines Python packages with a high-performance Rust core. Because the architecture relies on compiled native code for performance-critical operations, the repository provides several explicit build and compilation pathways for developers, packagers, and container deployments.

Build Targets and Compilation Pathways

The project uses a Makefile as the central façade for all build operations, defining distinct targets for different compilation needs.

Native Proxy Binary

The make build-proxy command compiles the standalone headroom-proxy binary using Cargo. This target runs cargo build --release -p headroom-proxy and strips the resulting binary for size optimization. The output is a native executable suitable for deployment without Python dependencies.

Python Wheel with Rust Extension

Running make build-wheel invokes Maturin to produce a PEP 517-compliant wheel. This packages both the Python source code and the compiled Rust extension (headroom._core) into a single distributable artifact. The wheel is output to dist/ with platform-specific tags (e.g., manylinux).

Development Build and Test

For local development, make test-parity performs a complete development cycle: it activates a Python virtual environment, builds the Rust extension in editable mode using maturin develop, and executes parity tests against stored fixtures to verify Python-Rust semantic equivalence.

CI Pre-Check

The make ci-precheck target serves as a local CI gate, executing cargo fmt --check, cargo clippy, and cargo test alongside the Python parity build and tests. This ensures code quality and compilation success before submitting changes.

Automated Build Scripts

For convenience, the repository includes scripts/build_rust_extension.sh, a Bash wrapper that automates the development build process. The script performs three validation steps: it confirms a virtual environment is active, executes pip install -e . (which triggers Maturin to invoke Cargo), and verifies that the compiled extension exports the expected symbols (DiffCompressor and SmartCrusher).

Docker Multi-Stage Build

The Dockerfile implements a multi-stage build strategy that isolates compilation dependencies from the final runtime image.

• Builder stage: Installs build-essential, g++, the Rust toolchain via rustup, and runs uv pip install ".[proxy,code]" to compile both the wheel and proxy binary.
• Runtime stage: Copies only the compiled artifacts (site-packages and headroom-proxy binary) into a slim or distroless base image, eliminating build tools from the production environment.

Build Prerequisites and Toolchain

Compiling Headroom from source requires:

• Rust toolchain (version ≥ 1.95) and cargo
• Python with pip or uv
• System compilers: build-essential and g++ (Linux) or equivalent
• Maturin: Declared as the build backend in pyproject.toml, it bridges Python packaging with Cargo

Step-by-Step Compilation Examples

Build the Rust Extension Locally

# Ensure virtual environment is active

source .venv/bin/activate

# Run the official helper script

bash scripts/build_rust_extension.sh

Compile the Native Proxy Binary

# Display all available targets

make help

# Build release binary (outputs target/release/headroom-proxy)

make build-proxy

Produce a Distribution Wheel

# Creates dist/headroom_ai-<version>-<platform>.whl

make build-wheel

Run Full Local CI Validation

# Executes Rust formatting, linting, tests, and Python parity checks

make ci-precheck

Build Container Image

# Multi-stage build compiles Rust components then creates slim image

docker build -t headroom:latest .

Key Build Files and Their Roles

• Makefile: Centralizes build orchestration for the proxy, wheel, and CI tasks.
• Cargo.toml: Defines the Rust workspace, crates, and dependencies; determines what Cargo compiles.
• pyproject.toml: Declares Maturin as the PEP 517 build backend, triggering Rust compilation during pip install.
• scripts/build_rust_extension.sh: Convenience wrapper ensuring the headroom._core module is present and functional.
• Dockerfile: Documents exact OS-level dependencies and the multi-stage compilation workflow.
• headroom/transforms/: Contains Python modules (e.g., smart_crusher.py) that import from the compiled Rust core.

Summary

• Headroom requires Rust compilation for the headroom._core extension and optional headroom-proxy binary.
• Pre-built wheels on PyPI (pip install headroom-ai) allow use without compilation.
• Make targets provide standardized workflows for development, testing, and packaging.
• Maturin serves as the build backend, invoking Cargo when Python packaging commands run.
• Docker multi-stage builds isolate compilation dependencies from production images.

Frequently Asked Questions

Do I need to compile Headroom if I install from PyPI?

No. Installing headroom-ai from PyPI provides a pre-built wheel containing the compiled Rust extension, allowing immediate use without a Rust toolchain or system compilers.

What Rust version is required to build Headroom?

The repository requires Rust toolchain version 1.95 or higher. The Dockerfile installs this via rustup, while local development requires manual installation before running make or pip install -e ..

How do I verify the Rust extension built correctly?

Run bash scripts/build_rust_extension.sh, which automatically checks for the presence of the headroom._core module and verifies that it exports the DiffCompressor and SmartCrusher symbols. Alternatively, import headroom._core in Python after installation.

Can I build Headroom without Docker?

Yes. Local builds use standard Rust and Python tooling. Activate a virtual environment, ensure Rust is installed, then run make build-wheel or pip install -e . to compile the extension using Maturin.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}