Skip to content

BUILDING.md

Latest commit

 

History

History
200 lines (148 loc) · 4 KB

BUILDING.md

File metadata and controls

200 lines (148 loc) · 4 KB

Building Mortie with Rust Acceleration

This guide covers building mortie with its Rust-accelerated morton indexing functions.

Prerequisites

Required

  • Python 3.10 or later
  • Rust toolchain (rustc, cargo)
  • Python packages: numpy

Installing Rust

Linux/macOS

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

Windows

Download and run rustup-init.exe

Verify Installation

rustc --version
cargo --version

Development Build

For local development with Rust acceleration:

# Clone repository
git clone https://github.com/espg/mortie.git
cd mortie

# Install maturin (Rust-Python build tool)
pip install maturin

# Build and install in development mode
maturin develop --release

# Or for debugging with symbols
maturin develop

Production Build

Build optimized wheels for distribution:

# Build wheel for current platform
maturin build --release

# Output will be in target/wheels/
ls -lh target/wheels/

Testing

Run tests with Rust implementation

pytest -v

Run Rust unit tests

cargo test

Run benchmarks

cargo bench

Installation from PyPI

Pre-built wheels are available for common platforms:

pip install mortie

This will automatically use the Rust implementation if a wheel is available for your platform.

Platform-Specific Notes

Linux

  • Uses manylinux wheels for broad compatibility
  • Supports x86_64 and aarch64 architectures

macOS

  • Separate wheels for Intel (x86_64) and Apple Silicon (aarch64)
  • Minimum macOS version: 10.12

Windows

  • Requires Visual Studio Build Tools or equivalent
  • Supports x86_64 architecture

Build Options

Release Build (Optimized)

maturin develop --release
  • Full optimizations (opt-level = 3)
  • Link-time optimization (LTO)
  • Stripped binaries
  • ~30-50% faster than debug builds

Debug Build (Fast Compilation)

maturin develop
  • Includes debug symbols
  • Faster compilation
  • Easier debugging with rust-gdb/rust-lldb

Profile Build

maturin develop --profile profiling
  • Optimized but with debug symbols
  • Useful for performance profiling

Troubleshooting

"maturin: command not found"

pip install --upgrade maturin

"Rust toolchain not found"

# Install rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Or update existing installation
rustup update

Build fails on Windows

Ensure you have Visual Studio Build Tools installed:

  1. Download from: https://visualstudio.microsoft.com/downloads/
  2. Install "Desktop development with C++"
  3. Restart terminal and try again

Import error: "cannot import name '_rustie'"

The Rust extension wasn't built. Run:

maturin develop --release

Tests fail after rebuild

Clean build artifacts:

cargo clean
maturin develop --release
pytest -v

Performance Comparison

Performance comparison of Rust vs Python (reference) implementations:

Benchmark Rust Python (reference) Speedup
Scalar operations 0.14 µs 10.69 µs 78.6x
Small arrays (1K) 1.93 ms 4.14 ms 2.1x
Large arrays (100K) 1.85 ms 410.59 ms 222.2x
Real-world (1.2M coords) 102.51 ms 5109.15 ms 49.8x

The Rust implementation provides dramatic performance improvements, especially for large datasets.

CI/CD

GitHub Actions automatically builds wheels for:

  • Linux (x86_64, aarch64)
  • macOS (x86_64, aarch64)
  • Windows (x86_64)
  • Python 3.10, 3.11, 3.12, 3.13

See .github/workflows/build-wheels.yml for details.

Contributing

When modifying Rust code:

  1. Run Rust tests: cargo test
  2. Run Python tests: pytest -v
  3. Run benchmarks: cargo bench
  4. Format code: cargo fmt
  5. Check lints: cargo clippy

Further Reading