Build Requirements for iroh: A Complete Guide to Compiling from Source

Building iroh requires Rust 1.75 or later, a working C compiler toolchain, and pkg-config on Unix systems, with optional OpenSSL headers and the Protocol Buffers compiler for specific features.

The iroh distributed systems library from n0-computer provides peer-to-peer networking primitives written in pure Rust. Understanding the build requirements for iroh ensures you can compile the core library, DNS utilities, and relay server from source without encountering missing dependency errors.

Core Build Requirements

Rust Toolchain

The minimum supported Rust version (MSRV) is defined in the rust-version field of iroh/Cargo.toml. As of the latest stable release, Rust 1.75 is required. Install the toolchain via rustup:

rustup install stable
rustup default stable

Cargo is included with the Rust toolchain and handles all crate dependencies automatically.

C/C++ Build Tools

Several dependencies—notably the ring crate used for cryptographic operations—compile native C code during the build process. You must have a working C compiler available:

• Linux: gcc or clang
• macOS: Xcode Command Line Tools (clang)
• Windows: Microsoft Visual C++ Build Tools (MSVC)

pkg-config

On Linux and macOS, the build system requires pkg-config to locate system libraries. This utility is typically installed by default on macOS with Xcode tools, but on Linux distributions you may need to install it explicitly:

# Debian/Ubuntu

sudo apt-get install pkg-config

# macOS (if not present)

brew install pkg-config

Optional Dependencies by Feature

OpenSSL Development Headers

If you enable the optional openssl feature flag in iroh/Cargo.toml, you must provide OpenSSL development headers and libraries. This feature is disabled by default in favor of rustls.

Install the required packages:

• Debian/Ubuntu: libssl-dev
• macOS: openssl via Homebrew (with appropriate PKG_CONFIG_PATH export)
• Windows: OpenSSL binaries via vcpkg or Strawberry Perl

Protocol Buffers Compiler

The iroh-dns crate defined in iroh-dns/Cargo.toml uses build = "build.rs" to compile .proto files at build time. You must install protoc version 3.14 or higher:

# Debian/Ubuntu

sudo apt-get install protobuf-compiler

# macOS

brew install protobuf

# Verify version

protoc --version

The protobuf-codegen crate is invoked automatically by Cargo once the compiler is present.

Cross-Compilation Targets

The iroh codebase supports cross-compilation to numerous targets including x86_64-unknown-linux-musl, Android architectures, and various ARM boards. The CI configuration files in .github/workflows/*.yml demonstrate the exact setup.

Add your target toolchain:

# Static musl build

rustup target add x86_64-unknown-linux-musl

# Android

rustup target add aarch64-linux-android

# ARMv7

rustup target add armv7-unknown-linux-gnueabihf

For static musl builds, you also need the musl-tools package on Debian/Ubuntu or the equivalent musl-gcc wrapper.

Docker and Build Automation

Docker Requirements

To build the relay server container defined in docker/, you need Docker 20.10 or later with docker-buildx enabled. The repository provides ready-to-use images but building locally requires:

cd docker
docker build -t iroh-relay .

For cross-platform images:

docker buildx build --platform linux/amd64,linux/arm64 -t iroh-relay .

cargo-make

The repository includes a Makefile.toml for task automation. Install cargo-make to use shortcuts:

cargo install cargo-make
cargo make  # Builds and tests

Step-by-Step Build Instructions

Basic Debug Build

Clone the repository and build the workspace:

git clone https://github.com/n0-computer/iroh.git
cd iroh
cargo build

This compiles the core iroh crate and all workspace members using your system C compiler for native dependencies.

Static Binary Release

For a fully static Linux binary suitable for deployment:

# Install prerequisites

rustup target add x86_64-unknown-linux-musl
sudo apt-get install musl-tools

# Build

cargo build --release --target x86_64-unknown-linux-musl

The resulting binary at target/x86_64-unknown-linux-musl/release/iroh requires no shared libraries.

Build with DNS Support

If working with the iroh-dns crate, ensure protoc is installed, then build specifically:

cargo build -p iroh-dns

Summary

• Rust 1.75+ is mandatory, specified in iroh/Cargo.toml via the rust-version field.
• C compiler is required for native dependencies like ring.
• pkg-config is necessary on Unix systems for library discovery.
• OpenSSL headers are only needed if explicitly enabling the openssl feature.
• protoc 3.14+ is required to build the iroh-dns crate from iroh-dns/Cargo.toml.
• Cross-compilation to musl, Android, and ARM targets requires additional rustup targets and potentially system linkers.

Frequently Asked Questions

What is the minimum Rust version required to build iroh?

According to the rust-version field in iroh/Cargo.toml, you need Rust 1.75 or later. This minimum version ensures compatibility with dependencies like quinn and rustls while maintaining stable async trait support.

Do I need OpenSSL to build iroh?

No, OpenSSL is optional. By default, iroh uses rustls and the ring crate for cryptography. You only need OpenSSL development headers if you explicitly enable the openssl feature flag in your Cargo.toml dependencies.

Can I build iroh for Android or embedded devices?

Yes, iroh supports cross-compilation to Android (aarch64-linux-android, armv7-linux-androideabi) and various ARM boards. You must install the appropriate rustup target and provide the Android NDK toolchain for mobile targets. The CI workflows in .github/workflows/ contain working examples for these builds.

How do I build a static binary that runs without shared libraries?

Use the x86_64-unknown-linux-musl target with musl-tools installed. Run rustup target add x86_64-unknown-linux-musl, install musl-gcc, then execute cargo build --release --target x86_64-unknown-linux-musl. This produces a statically-linked binary in target/x86_64-unknown-linux-musl/release/ that runs on any Linux distribution without requiring glibc.

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