Installation & Build

This section describes how to clone the EnerOS source code from GitHub, understand the project structure, choose appropriate build options, run tests, perform cross-compilation, and use Docker to build distributable images.

Clone the Repository

EnerOS source code is hosted on GitHub: https://github.com/Gawg-AI/EnerOS.

Clone via HTTPS (Most Common)

git clone https://github.com/Gawg-AI/EnerOS.git
cd EnerOS

Clone via SSH (For Contributors)

git clone git@github.com:Gawg-AI/EnerOS.git
cd EnerOS

Clone via GitHub CLI

# Install GitHub CLI (if not installed)
# Ubuntu
sudo apt install gh
# macOS
brew install gh

# Clone
gh repo clone Gawg-AI/EnerOS
cd EnerOS

Shallow Clone (Save Bandwidth)

# Pull only the latest commit
git clone --depth 1 https://github.com/Gawg-AI/EnerOS.git

# Pull the latest 10 commits
git clone --depth 10 https://github.com/Gawg-AI/EnerOS.git

Switch to a Specific Version

# List all tags
git tag -l

# Switch to version 0.47.0
git checkout v0.47.0

# Or switch to the latest code on the main branch
git checkout main
git pull

Project Structure Overview

EnerOS uses a Cargo workspace to organize 56 crates:

EnerOS/
├── crates/           # 56 Rust crates (libraries + binaries)
│   ├── eneros-core/             # Kernel foundation
│   ├── eneros-topology/         # Grid topology
│   ├── eneros-powerflow/        # Power flow calculation
│   ├── eneros-constraint/       # Security constraints
│   ├── eneros-equipment/        # Equipment models
│   ├── eneros-agent/            # Agent runtime
│   ├── eneros-tool/             # Agent tools
│   ├── eneros-reasoning/        # Reasoning engine
│   ├── eneros-gateway/          # Real-time safety gateway
│   ├── eneros-trust/            # Trust & CA
│   ├── eneros-ids/              # Intrusion detection
│   ├── eneros-audit/            # Audit logging
│   ├── eneros-timeseries/       # Time-series storage
│   ├── eneros-multiregion/      # Multi-region
│   ├── eneros-tenant/           # Multi-tenant
│   └── ...                      # Remaining 41 crates
├── os/               # OS service layer
│   ├── init/                    # Initialization
│   ├── rt/                      # Real-time domain
│   ├── agentos/                 # AgentOS abstraction
│   └── hal/                     # Hardware abstraction layer
├── docs/             # Project documentation
├── examples/         # Example code
├── tests/            # Integration tests
├── benches/          # Performance benchmarks
├── Cargo.toml        # Workspace configuration
├── Cargo.lock        # Dependency lockfile
├── eneros.toml       # Default runtime configuration
└── Dockerfile        # Container build

Key Binaries

Build

Release Build (Recommended for Production)

cargo build --release

Build artifacts are located in target/release/, with all optimizations enabled (opt-level=3, LTO optional).

Debug Build (Development & Debugging)

cargo build

Build artifacts are located in target/debug/, with faster compilation, debug symbols, and assertions included.

Build a Specific Crate

# Build only the core library
cargo build -p eneros-core

# Build only the Agent runtime
cargo build -p eneros-agent

# Build only the API server
cargo build -p eneros-api

# Build only the command-line tool
cargo build -p enerosctl

Build Options Details

Feature Flags

EnerOS controls optional features via Cargo features:

# Enable real-time domain
cargo build --release --features "realtime"

# Enable Dashboard
cargo build --release --features "dashboard"

# Enable multi-tenant
cargo build --release --features "multi-tenant"

# Enable all optional features
cargo build --release --all-features

# Disable default features
cargo build --release --no-default-features

LTO and Optimization Configuration

For more aggressive optimization, edit .cargo/config.toml:

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true

Build Artifacts Description

After building, the target/release/ directory contains:

target/release/
├── eneros-api             # API server main binary
├── enerosctl              # CLI tool
├── eneros-gateway         # Safety gateway
├── eneros-agent           # Agent runtime
├── eneros-rt              # Real-time domain daemon
├── libeneros_core.rlib    # Static library
├── libeneros_topology.rlib
└── ...                    # Other crate artifacts

View binary size:

ls -lh target/release/eneros-api

Run Tests

EnerOS has 7300+ test cases covering all core functionality.

Run All Tests

# Run all tests (including unit and integration tests)
cargo test

# Run in release mode (faster)
cargo test --release

# Compile tests without running
cargo test --no-run

Run Tests for a Specific Crate

# Power flow calculation tests
cargo test -p eneros-powerflow

# Topology analysis tests
cargo test -p eneros-topology

# Constraint validation tests
cargo test -p eneros-constraint

# Agent runtime tests
cargo test -p eneros-agent

Run Specific Test Functions

# Filter by name
cargo test -p eneros-powerflow newton_raphson

# Multiple keywords
cargo test -p eneros-topology -- "test_island"

# Show println! output
cargo test -- --nocapture

# Run only ignored tests
cargo test -- --ignored

Integration Tests

# Run integration tests in the tests/ directory
cargo test --test '*'

# Run a specific integration test file
cargo test --test powerflow_integration

Benchmarks

# Run all benchmarks
cargo bench

# Run benchmarks for a specific crate
cargo bench -p eneros-powerflow

# Output to file
cargo bench -- --save-baseline my_baseline

Test Coverage

# Install tarpaulin (Linux only)
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --workspace --out Html

# View report
# Output is in tarpaulin-report.html

Test Result Example

running 7342 tests
test result: ok. 7342 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running tests/powerflow_integration.rs
test powerflow_ieee14 ... ok
test powerflow_ieee30 ... ok
test powerflow_ieee118 ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Cross-Compilation

EnerOS supports cross-compilation to multiple target platforms.

Cross-Compile to ARM64 Linux

# Add target
rustup target add aarch64-unknown-linux-gnu

# Install cross toolchain (Ubuntu)
sudo apt install -y gcc-aarch64-linux-gnu

# Configure linker, edit ~/.cargo/config.toml
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

# Build
cargo build --release --target aarch64-unknown-linux-gnu

Artifacts are located in target/aarch64-unknown-linux-gnu/release/.

Cross-Compile to Windows

# Add target (MSVC)
rustup target add x86_64-pc-windows-msvc

# Build (requires MSVC toolchain)
cargo build --release --target x86_64-pc-windows-msvc

Cross-Compile to WebAssembly

# Add WASI target
rustup target add wasm32-wasi

# Build
cargo build --release --target wasm32-wasi -p eneros-core

Using the cross Tool

# Install cross (depends on Docker)
cargo install cross

# One-click cross-compilation (no manual toolchain configuration)
cross build --target aarch64-unknown-linux-gnu

# Cross-run tests
cross test --target aarch64-unknown-linux-gnu

Docker Build

EnerOS provides a multi-stage Dockerfile that can directly build distributable container images.

Build the Image

# Build default image
docker build -t eneros:latest .

# Build a specific version
docker build -t eneros:0.47.0 .

# Specify platform
docker buildx build --platform linux/amd64,linux/arm64 -t eneros:latest .

Dockerfile Description

EnerOS’s Dockerfile uses multi-stage builds:

The final image is approximately 80 MB, containing only the binaries and necessary runtime libraries.

Run the Container

# Run the API server
docker run -d \
    -p 8080:8080 \
    -v $(pwd)/eneros.toml:/etc/eneros/eneros.toml \
    -v $(pwd)/data:/var/lib/eneros \
    --name eneros-api \
    eneros:latest

# View logs
docker logs -f eneros-api

# Enter the container
docker exec -it eneros-api bash

docker-compose Example

version: '3.8'
services:
  eneros-api:
    image: eneros:latest
    ports:
      - "8080:8080"
    volumes:
      - ./eneros.toml:/etc/eneros/eneros.toml
      - eneros-data:/var/lib/eneros
    environment:
      - ENEROS_LOG=info
    restart: unless-stopped

volumes:
  eneros-data:

docker compose up -d

Common Build Issues

Problem 1: OpenSSL Linking Error

error: failed to run custom build command for `openssl-sys`

Solution:

# Ubuntu / Debian
sudo apt install -y libssl-dev pkg-config
export OPENSSL_DIR=/usr/lib/ssl
export PKG_CONFIG_PATH=/usr/lib/pkgconfig

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

# Use vendored OpenSSL (no system library required)
cargo build --release --features openssl-vendored

Problem 2: SQLite Linking Error

error: linking with `cc` failed: exit code: 1
note: undefined reference to `sqlite3_open`

Solution:

# Ubuntu
sudo apt install -y libsqlite3-dev

# macOS
brew install sqlite
export SQLITE3_LIB_DIR=$(brew --prefix sqlite)/lib

# Use bundled SQLite
cargo build --release --features sqlite-bundled

Problem 3: ring crate Compilation Failure

error: failed to run custom build command for `ring`

Cause: Missing cmake or C compiler.

Solution:

# Ubuntu
sudo apt install -y cmake build-essential

# macOS
brew install cmake

Problem 4: Build Timeout or Stuck on Dependency Download

# Use offline mode (requires a prior online cargo fetch)
cargo build --offline

# Increase network timeout
export CARGO_NET_TIMEOUT=120
export CARGO_NET_RETRY=5

# Configure mirror (see prerequisites.md)

Problem 5: error: package 'eneros-core' not found in workspace

Cause: Command not executed from the repository root, or workspace configuration is broken.

Solution:

# Confirm you are in the repository root
cd /path/to/EnerOS

# Check workspace configuration
cat Cargo.toml | head -10
# Should see a [workspace] section

# Regenerate Cargo.lock
rm Cargo.lock
cargo generate-lockfile

Problem 6: Compile error error[E0463]: can't find crate

Cause: Missing dependency due to feature not enabled.

Solution:

# Check the crate's features
cargo tree -p eneros-agent --features default

# Enable required feature
cargo build --release --features "realtime,dashboard"

Problem 7: Out of Memory (OOM killed)

# Limit parallel jobs
CARGO_BUILD_JOBS=2 cargo build --release

# Add swap (Linux)
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Next Steps

• First Run - Start the API server and run power flow calculation