Prerequisites

This section describes all the preparation work required before setting up the EnerOS development and runtime environment, including operating system requirements, Rust toolchain installation, system dependencies for each platform, Docker image options, as well as environment validation and common troubleshooting.

System Requirements

EnerOS consists of 56 Rust crates. Compilation requires significant memory and disk space, and the runtime is latency-sensitive. The table below lists minimum and recommended configurations:

Real-Time Domain Extension Requirements

To enable EnerOS’s real-time domain (Protection / Control / Stability), the following additional requirements must be met:

Install Rust Toolchain

EnerOS uses Rust 1.70+. It is recommended to install and manage multiple toolchain versions via the official rustup tool.

Install rustup

Linux / macOS

# Download and install rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Select default options during installation (press 1 and Enter)

# Reload the current shell's environment variables
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version
rustup --version

Windows

Download and run rustup-init.exe, and select default installation as prompted. After installation, reopen PowerShell:

rustc --version
cargo --version
rustup --version

Install Stable Toolchain

# Install the latest stable version
rustup toolchain install stable

# Set as default
rustup default stable

# Verify the current default toolchain
rustup show

rustup Components

The following components are recommended for EnerOS compilation and development:

# Add recommended components
rustup component add rustfmt clippy rust-src rust-analyzer

# Add optional component (used when developing unsafe code)
rustup component add miri

Toolchain Management

# List installed toolchains
rustup toolchain list

# Install nightly (only needed when using certain unstable features)
rustup toolchain install nightly

# Upgrade all toolchains
rustup update

# Uninstall a toolchain
rustup toolchain uninstall nightly

Add Target Platforms (Cross-Compilation)

# List all supported targets
rustup target list

# Add aarch64-unknown-linux-gnu target (ARM64 Linux)
rustup target add aarch64-unknown-linux-gnu

# Add x86_64-pc-windows-gnu target (Windows GNU)
rustup target add x86_64-pc-windows-gnu

# Add wasm32-wasi target (WASI)
rustup target add wasm32-wasi

System Dependencies

Some EnerOS crates depend on native system libraries such as OpenSSL, SQLite, and CMake. Please install them according to your operating system.

Ubuntu / Debian

# Update package index
sudo apt update

# Install build toolchain and base dependencies
sudo apt install -y \
    build-essential \
    pkg-config \
    libssl-dev \
    libsqlite3-dev \
    cmake \
    git \
    curl \
    clang \
    libclang-dev

CentOS / RHEL / Rocky Linux

# Enable EPEL repository
sudo dnf install -y epel-release

# Install dependencies
sudo dnf install -y \
    gcc \
    gcc-c++ \
    make \
    pkgconfig \
    openssl-devel \
    sqlite-devel \
    cmake \
    git \
    clang \
    clang-devel

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install openssl@3 sqlite pkg-config cmake

If you encounter OpenSSL linking issues on macOS, add the following to ~/.zshrc or ~/.bash_profile:

export OPENSSL_DIR=$(brew --prefix openssl@3)
export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig"

Windows

Windows recommends using the MSVC toolchain. Install Visual Studio Build Tools and select the “Desktop development with C++” workload (includes MSVC, Windows SDK, CMake).

# Install Chocolatey (if not installed)
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# Install dependencies
choco install openssl pkgconfiglite cmake git -y

After installation, set environment variables (PowerShell):

# Set OpenSSL path (adjust to actual installation path)
[Environment]::SetEnvironmentVariable("OPENSSL_DIR", "C:\Program Files\OpenSSL-Win64", "User")
[Environment]::SetEnvironmentVariable("PKG_CONFIG_PATH", "C:\Program Files\OpenSSL-Win64\lib\pkgconfig", "User")

# Verify after restarting PowerShell
echo $env:OPENSSL_DIR

Docker Approach

If you prefer not to install many dependencies on the host, you can use the official Docker image, which comes with a complete EnerOS build environment pre-installed.

Pull Official Image

# Pull the latest stable build image
docker pull ghcr.io/gawg-ai/eneros-build:latest

# Pull a specific version
docker pull ghcr.io/gawg-ai/eneros-build:0.47.0

Build in Container

# Start a build container and mount the source directory
docker run -it --rm \
    -v $(pwd):/workspace \
    -w /workspace \
    ghcr.io/gawg-ai/eneros-build:latest \
    bash

# Build inside the container
cargo build --release

Customize with Dockerfile

FROM ghcr.io/gawg-ai/eneros-build:latest

WORKDIR /workspace
COPY . .

RUN cargo build --release

EXPOSE 8080
CMD ["./target/release/eneros-api"]

# Build custom image
docker build -t my-eneros .

# Run
docker run -d -p 8080:8080 --name eneros my-eneros

Validate Environment

1. Verify Rust Toolchain

# Check Rust version (should be ≥ 1.70)
rustc --version

# Check Cargo version
cargo --version

# Check rustup components
rustup component list --installed

Expected output example:

rustc 1.75.0 (82e1608df 2023-12-21)
cargo 1.75.0 (1d8b05cdd 2023-11-20)
cargo-x86_64-unknown-linux-gnu (default)
rustfmt 1.7.0-stable (82e1608d 2023-12-21)
clippy 0.1.75 (82e1608d 2023-12-21)

2. Create Test Project

# Create test project
cargo new hello_eneros
cd hello_eneros

# Modify main.rs to reference OpenSSL (optional, verifies system library linking)
cat > src/main.rs <<'EOF'
fn main() {
    println!("Hello, EnerOS!");
    println!("OpenSSL version: {}", openssl::version::version());
}
EOF

# Add openssl dependency
cargo add openssl

# Build and run
cargo run

Expected output:

Hello, EnerOS!
OpenSSL version: OpenSSL 3.0.x ...

3. Verify SQLite Linking

cargo add rusqlite

Modify src/main.rs:

use rusqlite::Connection;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conn = Connection::open_in_memory()?;
    conn.execute(
        "CREATE TABLE enerostest (id INTEGER PRIMARY KEY, name TEXT)",
        [],
    )?;
    println!("SQLite OK");
    Ok(())
}

cargo run
# Output: SQLite OK

Common Troubleshooting

Problem 1: error: linker 'cc' not found

Cause: C compiler not installed.

Solution:

# Ubuntu / Debian
sudo apt install -y build-essential

# macOS
xcode-select --install

# Windows: Install Visual Studio Build Tools and select C++ workload

Problem 2: error: failed to run custom build command for 'openssl-sys'

Cause: OpenSSL library not found or pkg-config not configured correctly.

Solution:

# Ubuntu
sudo apt install -y libssl-dev pkg-config

# macOS
brew install openssl@3 pkg-config
export OPENSSL_DIR=$(brew --prefix openssl@3)

# Windows
choco install openssl pkgconfiglite
# Set OPENSSL_DIR environment variable to point to the installation directory

Problem 3: error: could not find library 'sqlite3'

Cause: SQLite development library not installed.

Solution:

# Ubuntu
sudo apt install -y libsqlite3-dev

# macOS
brew install sqlite

# Windows
choco install sqlite

Problem 4: cargo build runs out of memory (OOM)

Cause: EnerOS is a large workspace; parallel compilation of 56 crates consumes significant memory.

Solution: Limit parallelism

# Limit the number of concurrent compilation units
export CARGO_BUILD_JOBS=2

# Or configure in ~/.cargo/config.toml
[build]
jobs = 2

Problem 5: error: linking with 'link.exe' failed on Windows

Cause: Missing MSVC toolchain or Windows SDK.

Solution:

1. Re-run Visual Studio Installer
2. Select the “Desktop development with C++” workload
3. Ensure “Windows 10/11 SDK” is checked
4. Reopen the terminal and retry

Problem 6: Network download from crates.io fails

Cause: Network access restricted.

Solution: Configure a mirror, edit ~/.cargo/config.toml:

[source.crates-io]
replace-with = "ustc"

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"

Or use the Tsinghua mirror:

[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

Next Steps

• Installation & Build - Clone the EnerOS repository and build