Development Workflow en

中文 | English

Development Workflow

Maintained version: v0.51.2 ｜ Last updated: 2026-07-06

This page summarizes the EnerOS development workflow: workspace organization / adding a new Agent / adding a new protocol / adding a new plugin / debugging tips. For the full developer guide see the main repo docs/developer-guide.md and CONTRIBUTING.md.

Workspace Organization

EnerOS uses a Cargo workspace with 79 members: 56 libraries + 23 binaries + 3 SDK/macros. For the full index see the Crate Index page.

Dependencies are strictly top-down; reverse and circular dependencies are forbidden (see Layered Dependencies).

Development Environment

Item	Requirement
Rust	1.75+, edition 2021
Platform	Linux x86_64/aarch64 (production) / Windows & macOS (core library development)
Recommended components	rustfmt / clippy / rust-src
IDE	VS Code + rust-analyzer

rustup component add rustfmt clippy rust-src

Building core libraries on Windows/macOS (excluding eneros-installer):

cargo build --workspace --exclude eneros-installer

Adding a New Agent

1. Implement the Agent logic: create a new module under crates/eneros-agent/src/agents/, implementing the decision loop and message handling
2. Create the binary entry: create a new directory under crates/eneros-agent/bins/ containing Cargo.toml and src/main.rs
3. Register in workspace: add the path to the members list in the root Cargo.toml
4. Configure init.toml: add a startup config (binary path / args / resource quota) in os/rootfs/files/etc/eneros/init.toml
5. Build verification:

cargo build -p my-agent
cargo test -p eneros-agent

See the main repo docs/developer-guide.md §4.

Adding a New Protocol Adapter

1. Create the adapter module: new directory under crates/eneros-device/src/adapters/
2. Implement the DeviceAdapter trait: refer to the trait definition in crates/eneros-device/src/adapter.rs
3. Register with DeviceManager: declare it in crates/eneros-device/src/adapters/mod.rs
4. Protocol conformance tests: add test cases under tests/protocol_conformance/
5. Fuzz target (optional): add a fuzz target under fuzz/

See the main repo docs/developer-guide.md §5.

Adding a New Plugin

See the Operations & Plugins page and the main repo docs/plugin-development.md.

Summary:

1. Create a cdylib crate
2. Implement the Plugin trait + the corresponding ProtocolPlugin / AgentPlugin / AnalysisPlugin trait
3. Use the #[eneros_plugin] macro to auto-generate the C ABI entry
4. Write a manifest.toml manifest
5. Sign with Ed25519
6. Deploy to ~/.eneros/plugins/

Debugging Tips

rust-analyzer config

{
  "rust-analyzer.checkOnSave.command": "clippy",
  "rust-analyzer.cargo.features": "all"
}

LLDB debugging eneros-api

{
  "type": "lldb",
  "request": "launch",
  "name": "debug eneros-api",
  "cargo": {
    "args": ["build", "--package", "eneros-api"],
    "filter": { "kind": "bin" }
  },
  "args": ["run", "--config", "eneros.toml"],
  "cwd": "${workspaceFolder}"
}

Dynamic log level adjustment

ENEROS_OBSERVABILITY__LOG_LEVEL=debug ./target/release/eneros-api run

Or at runtime via API:

curl -X POST http://localhost:8080/api/config/reload

Profiling

# Generate a flamegraph
cargo flamegraph --bin eneros-api -- run --config eneros.toml

# Benchmarks
cargo bench --workspace

Quality Gates

Every PR automatically runs:

Gate	Command	On failure
Formatting	cargo fmt --all -- --check	Blocks merge
Lint	cargo clippy --workspace --all-targets -- -D warnings	Blocks merge
Build	cargo build --workspace	Blocks merge
Test	cargo test --workspace	Blocks merge
Docs	cargo doc --workspace --no-deps	Warning
Dependencies	cargo deny check	Blocks merge
Coverage	llvm-cov	Threshold check

See the Testing Strategy page.

Commit Conventions

Follow CONTRIBUTING.md:

• Use conventional commits (feat: / fix: / docs: / refactor: / test: / chore:)
• Every PR must update the corresponding version section in CHANGELOG.md
• On a new release, move completed items from ROADMAP.md to CHANGELOG.md
• Major architecture decisions require a new ADR

Related Documentation

• Main repo docs/developer-guide.md — Full developer guide
• Main repo CONTRIBUTING.md — Contribution guidelines
• Wiki Crate Index — 79-member list
• Wiki Layered Dependencies — Dependency direction rules
• Wiki Testing Strategy — Testing and quality gates
• Wiki Operations & Plugins — Plugin development details