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

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 manifest. This version pin ensures compatibility with the libp2p crates and other dependencies used by the networking engine.

# 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, 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:

# 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 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	Rust manifest defining dependencies, version requirements (1.98+), and crate metadata
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	TypeScript wrapper that loads and interfaces with the compiled .node binary
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.
• 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.

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 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 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.

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