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

> Learn how to build Rust extensions and native binaries for Headroom using Make, Maturin, and Cargo. Explore the complete guide to compiling Headroom for advanced usage.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-21

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml), it bridges Python packaging with Cargo

## Step-by-Step Compilation Examples

### Build the Rust Extension Locally

```bash

# 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

```bash

# Display all available targets

make help

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

make build-proxy

```

### Produce a Distribution Wheel

```bash

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

make build-wheel

```

### Run Full Local CI Validation

```bash

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

make ci-precheck

```

### Build Container Image

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/Cargo.toml)**: Defines the Rust workspace, crates, and dependencies; determines what Cargo compiles.
- **[`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml)**: Declares Maturin as the PEP 517 build backend, triggering Rust compilation during `pip install`.
- **[`scripts/build_rust_extension.sh`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.