# Build Requirements for Maka's Peer Mesh Native Addon: Complete Setup Guide

> Build Maka's Peer Mesh native addon by meeting Rust 1.98+, Node.js 18+, C/C++ compilers, and Python 3.7+ requirements. Learn how to compile the addon and generate the .node binary.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-09

---

**To compile Maka's Peer Mesh native addon, you need Rust toolchain 1.98 or higher, Node.js 18+, platform-specific C/C++ compilers, and Python 3.7+, then run `npm run build` to generate the `.node` binary from the Rust source.**

The Peer Mesh native addon in the `apache/maka` repository provides high-performance networking capabilities for the JavaScript runtime host. Located in `native/runtime-host-peer`, this Rust-based N-API module implements libp2p networking primitives that power Maka's decentralized peer-to-peer transport layer.

## Core Build Requirements for the Peer Mesh Native Addon

Building the native addon requires coordinating both Rust and Node.js toolchains. The following components must be present on your system before compilation.

### Rust Toolchain (1.98 or Higher)

The native implementation requires a minimum Rust version of **1.98**, as specified in the [`Cargo.toml`](https://github.com/apache/maka/blob/main/Cargo.toml) manifest. This version pin ensures compatibility with the libp2p crates and other dependencies used by the networking engine.

```toml

# native/runtime-host-peer/Cargo.toml

[package]
name = "runtime-host-peer"
rust-version = "1.98"

```

You need both **rustc** and **Cargo** installed. The build process invokes Cargo directly to compile the Rust library into a shared object that Node.js can load.

### Node.js Runtime and npm

The JavaScript integration layer requires **Node.js 18 or higher** and **npm 8 or higher**. The runtime host package uses the `node-addon-api` (or `@napi-rs/cli`) to bridge between Rust and JavaScript.

The native module is loaded by the transport layer at runtime via [`packages/runtime-host/src/transport/peer-native.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/peer-native.ts), which dynamically imports the compiled `.node` binary.

### Platform-Specific C/C++ Build Tools

Because N-API modules link against system libraries, you must have native compilation tools installed for your platform:

- **Windows**: Visual Studio Build Tools with MSVC compiler
- **macOS**: Xcode Command Line Tools
- **Linux**: `make`, `gcc` or `clang`, and standard build essentials

These tools are required by `node-gyp` (or the NAPI-RS build pipeline) to link the final binary against Node.js's C++ ABI.

### Python for node-gyp

**Python 3.7 or higher** is mandatory for `node-gyp` on all platforms. The build scripts use Python during the compilation phase to generate platform-specific build files and manage the native compilation workflow.

### Optional: OpenSSL Development Headers

For Linux systems, install `libssl-dev` (Debian/Ubuntu) or `openssl-devel` (RHEL/CentOS) to enable TLS-encrypted transports. The Peer Mesh engine supports QUIC and TCP with TLS, which rely on OpenSSL libraries. macOS includes these libraries by default, while Windows uses native TLS APIs.

## Build Process and Compilation Flow

The repository uses an npm script to orchestrate the Rust compilation. From the repository root, execute the standard build pipeline:

```bash

# Install JavaScript dependencies including @napi-rs/cli

npm ci

# Compile the native addon (triggers scripts/build.mjs)

npm run build

```

The `npm run build` command executes `scripts/build.mjs`, which internally runs `cargo build --release` targeting the `native/runtime-host-peer` directory. This produces the `runtime-host-peer.node` binary and places it in the package's `dist` folder.

The JavaScript wrapper at [`packages/runtime-host/src/transport/peer-native.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/peer-native.ts) then loads this binary at runtime using `require()` or dynamic import, exposing the Rust networking primitives to the TypeScript runtime.

## Key Source Files and Architecture

Understanding the file structure helps when debugging build issues or contributing to the native code:

| File Path | Purpose |
|-----------|---------|
| [`native/runtime-host-peer/Cargo.toml`](https://github.com/apache/maka/blob/main/native/runtime-host-peer/Cargo.toml) | Rust manifest defining dependencies, version requirements (1.98+), and crate metadata |
| [`native/runtime-host-peer/src/lib.rs`](https://github.com/apache/maka/blob/main/native/runtime-host-peer/src/lib.rs) | N-API entry point exposing Rust functions to JavaScript via `#[module_exports]` |
| `native/runtime-host-peer/src/engine/*.rs` | Core Peer Mesh implementation including libp2p integration, QUIC/TCP handling, and relay logic |
| [`packages/runtime-host/src/transport/peer-native.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/peer-native.ts) | TypeScript wrapper that loads and interfaces with the compiled `.node` binary |
| [`packages/runtime-host/src/__tests__/peer-native.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/__tests__/peer-native.test.ts) | Test suite verifying native addon functionality |
| `scripts/build.mjs` | Build automation script that invokes Cargo and manages compilation flags |

## Troubleshooting Common Build Issues

If compilation fails, verify these specific requirements:

- **Rust version mismatch**: Run `rustc --version` and ensure it reports 1.98 or higher. The build will fail if the toolchain predates the `rust-version` pin in [`Cargo.toml`](https://github.com/apache/maka/blob/main/Cargo.toml).
- **Missing Python**: Ensure `python3` is in your PATH. The build scripts specifically require Python for generating native build configurations.
- **OpenSSL linking errors** (Linux): Install `libssl-dev` before building. Missing headers cause link-time failures when compiling the QUIC transport layer.
- **Node-API version conflicts**: Ensure you are building against a Node.js version compatible with the `@napi-rs/cli` version specified in [`packages/runtime-host/package.json`](https://github.com/apache/maka/blob/main/packages/runtime-host/package.json).

## Summary

To successfully build Maka's Peer Mesh native addon:

- Install **Rust 1.98+** with Cargo to compile the core networking engine
- Use **Node.js 18+** and **npm 8+** for the JavaScript build toolchain
- Provide **platform C/C++ compilers** (MSVC, Xcode CLT, or gcc/clang) and **Python 3.7+** for node-gyp integration
- Install **OpenSSL development headers** on Linux for TLS support
- Run `npm run build` from the repository root to execute the compilation pipeline

## Frequently Asked Questions

### What Rust version is required to build the Peer Mesh native addon?

You need **Rust 1.98 or higher**. The [`native/runtime-host-peer/Cargo.toml`](https://github.com/apache/maka/blob/main/native/runtime-host-peer/Cargo.toml) explicitly sets `rust-version = "1.98"` to ensure compatibility with the specific libp2p crate versions used by the networking engine. Earlier versions will reject the build with a compiler error.

### Where is the compiled native addon binary located after building?

The build process outputs `runtime-host-peer.node` into the `dist` folder of the runtime-host package. The [`peer-native.ts`](https://github.com/apache/maka/blob/main/peer-native.ts) module loads this binary at runtime using a platform-specific path resolution that looks for the `.node` file in the distribution directory.

### Do I need OpenSSL to build the Maka Peer Mesh addon on macOS?

No. While Linux requires `libssl-dev` or `openssl-devel` headers, macOS provides the necessary TLS libraries through the system Security framework and Xcode Command Line Tools. The build scripts automatically link against native macOS security APIs rather than OpenSSL on Apple platforms.

### Can I build the native addon without Node.js installed?

No. Although the core logic is written in Rust, the build pipeline requires Node.js and npm to execute `scripts/build.mjs` and to install the `@napi-rs/cli` tooling that generates the N-API bindings. You must have Node.js 18+ available to trigger the Cargo compilation and produce the loadable `.node` binary.