Thank you for your interest in contributing to the EoS ecosystem! This guide covers development setup for all seven repositories and the conventions we follow.

• Code of Conduct
• Repository Overview
• Prerequisites
• Development Setup
  • eos — Embedded OS
  • eboot — Bootloader
  • ebuild — Build System
  • eipc — Embedded IPC
  • eai — AI Layer
  • eni — Neural Interface
  • eos-sdk — Unified SDK
• Workflow
• Commit Message Convention
• Pull Request Guidelines
• Coding Standards
• Testing
• Issue Reporting
• License

We are committed to providing a welcoming and inclusive experience for everyone. Be respectful, constructive, and professional in all interactions. Harassment, discrimination, and disruptive behavior will not be tolerated.

• Git 2.30+
• A GitHub account with fork access

sudo apt update
sudo apt install -y \
  git build-essential cmake ninja-build \
  python3 python3-pip python3-venv \
  golang-go \
  gcc-arm-none-eabi gcc-aarch64-linux-gnu gcc-riscv64-linux-gnu

sudo dnf install -y \
  git gcc gcc-c++ cmake ninja-build \
  python3 python3-pip \
  golang \
  arm-none-eabi-gcc-cs

brew install cmake ninja python go
brew install --cask gcc-arm-embedded

# Install via winget
winget install Kitware.CMake
winget install Ninja-build.Ninja
winget install Python.Python.3.12
winget install GoLang.Go

# Or use WSL (recommended for cross-compilation)
wsl --install -d Ubuntu

# Create workspace
mkdir -p ~/EoS && cd ~/EoS

# Clone all repos
for repo in eos eboot ebuild eipc eai eni eos-sdk; do
  git clone https://github.com/embeddedos-org/$repo.git
done

cd ~/EoS/eos

# Build with tests
cmake -B build -DEOS_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

# Build for a specific product profile
cmake -B build -DEOS_PRODUCT=robot -DEOS_BUILD_TESTS=ON
cmake --build build

# Build with ebuild (if installed)
ebuild build

Key directories:

Test suites:

ctest --test-dir build -R test_hal         # HAL tests
ctest --test-dir build -R test_kernel      # Kernel tests
ctest --test-dir build -R test_crypto      # Crypto tests
ctest --test-dir build -R test_multicore   # Multicore tests

cd ~/EoS/eboot

# Native build (core libraries + tests, no board-specific code)
cmake -B build -DEBLDR_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

# Cross-compile for a specific board
cmake -B build -DEBLDR_BOARD=stm32f4 \
  -DCMAKE_TOOLCHAIN_FILE=toolchains/arm-none-eabi.cmake
cmake --build build

Key directories:

Adding a new board:

1. Create boards/<name>/board_<name>.h — memory map and constants
2. Create boards/<name>/board_<name>.c — implement eos_board_ops_t
3. Add eboot_add_board() in CMakeLists.txt
4. Add linker scripts if needed

cd ~/EoS/ebuild

# Install in development mode
pip install -e .

# Verify
ebuild --version
ebuild --help

# Run tests
python -m pytest tests/ -v

# Run the full pipeline test
python test_full_pipeline.py

# Run EoS AI tests
python tests/test_eos_ai.py

# Lint
flake8 ebuild/
black --check ebuild/
isort --check ebuild/

Key directories:

Adding a new build backend:

1. Create ebuild/build/backends/<name>_backend.py
2. Implement the backend interface (configure, build, clean, install)
3. Register in ebuild/build/dispatch.py
4. Add auto-detection rules (file patterns)
5. Add tests in tests/

cd ~/EoS/eipc

# Build Go components
go build ./...

# Run Go tests
go test ./... -v

# Run integration tests
go test ./tests/ -v -tags=integration

# Build C SDK
cd sdk/c
cmake -B build
cmake --build build
ctest --test-dir build --output-on-failure

# Lint Go code
golangci-lint run ./...

Key directories:

Adding a new transport:

1. Create transport/<name>/<name>.go
2. Implement the transport.Transport interface
3. Add tests in transport/<name>/<name>_test.go
4. Register in transport factory

cd ~/EoS/eai

# Build with tests
cmake -B build -DEAI_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

Key directories:

Adding a new connector (EAI-Framework):

1. Create framework/src/connector_<name>.c
2. Add header in framework/include/eai_fw/connector.h
3. Register in connector factory
4. Add a deployment profile in profiles/

cd ~/EoS/eni

# Build with tests
cmake -B build -DENI_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

Key directories:

Adding a new provider:

1. Create providers/<name>/<name>.c and <name>.h
2. Implement the provider contract from common/include/eni/provider_contract.h
3. Register in provider manager
4. Add tests in tests/

cd ~/EoS/eos-sdk

# Build with examples and tests
cmake -B build \
  -DEOS_SDK_BUILD_EXAMPLES=ON \
  -DEOS_SDK_BUILD_TESTS=ON \
  -DEOS_SDK_FETCH_DEPS=OFF  # Use local repos instead of fetching
cmake --build build
ctest --test-dir build --output-on-failure

# Build with specific packages disabled
cmake -B build \
  -DEOS_SDK_ENABLE_OS=ON \
  -DEOS_SDK_ENABLE_BOOT=ON \
  -DEOS_SDK_ENABLE_IPC=OFF \
  -DEOS_SDK_ENABLE_ENI=OFF \
  -DEOS_SDK_ENABLE_AI=OFF
cmake --build build

Key directories:

# Fork the repo on GitHub, then:
git clone https://github.com/<your-username>/<repo>.git
cd <repo>
git remote add upstream https://github.com/embeddedos-org/<repo>.git

git checkout -b feature/your-feature-name

Branch naming conventions:

• Follow the Coding Standards below
• Write tests for new functionality
• Keep commits focused and atomic

# C projects
cmake --build build && ctest --test-dir build --output-on-failure

# Python (ebuild)
python -m pytest tests/ -v && flake8 ebuild/ && black --check ebuild/

# Go (eipc)
go test ./... -v && golangci-lint run

git push origin feature/your-feature-name

Open a Pull Request on GitHub against the main branch.

<type>(<scope>): <short description>

<optional body>

Use the module name: hal, kernel, bootctl, crypto, cli, cmake, transport, etc.

feat(hal): add radar peripheral interface
fix(bootctl): correct CRC calculation for slot B
docs(eni): add provider integration guide
test(eipc): add shared memory transport tests
build(ebuild): add NuttX backend auto-detection

• Code compiles without warnings (-Wall -Wextra -Werror for C)
• All existing tests pass
• New tests added for new functionality
• Documentation updated if API changed
• Commit messages follow the convention above
• Branch is rebased on latest main

## Summary
Brief description of what this PR does.

## Changes
- Change 1
- Change 2

## Testing
How was this tested? Which test suites were run?

## Related Issues
Closes #XX (if applicable)

1. At least one maintainer approval required
2. CI must pass (build + tests on Linux/Windows/macOS)
3. No merge conflicts with main

• Standard: C11
• Style: 4-space indentation, snake_case for functions and variables
• Prefixes: eos_ for eos, eboot_/eos_ for eboot, eai_ for eai, eni_ for eni
• Headers: Include guards (#ifndef FOO_H / #define FOO_H / #endif)
• Comments: Doxygen-style for public APIs (/** @brief ... */)
• Warnings: Code must compile clean with -Wall -Wextra -Werror

/**
 * @brief Initialize the sensor subsystem.
 * @param config Sensor configuration.
 * @return 0 on success, negative error code on failure.
 */
int eos_sensor_init(const eos_sensor_config_t *config);

• Style: PEP 8, enforced by black and isort
• Line length: 88 characters (black default)
• Type hints: Encouraged for public functions
• Docstrings: Google style

def build(backend: str, config: BuildConfig) -> int:
    """Build the project using the specified backend.

    Args:
        backend: Build backend name (cmake, make, cargo, etc.).
        config: Build configuration from build.yaml.

    Returns:
        Exit code (0 for success).
    """

• Style: gofmt / goimports (standard Go formatting)
• Linting: golangci-lint
• Comments: GoDoc style for exported types and functions
• Error handling: Always check and return errors, no panics in library code

// Send transmits a message to the connected endpoint.
// Returns an error if the connection is closed or the message is invalid.
func (e *Endpoint) Send(msg Message) error {

C projects use CTest with simple assertion macros:

void test_sha256_known_vector(void) {
    uint8_t hash[32];
    eos_sha256("abc", 3, hash);
    assert(memcmp(hash, expected_hash, 32) == 0);
    printf("PASS: test_sha256_known_vector\n");
}

Python uses pytest:

def test_cmake_backend_detect():
    assert detect_backend("/path/with/CMakeLists.txt") == "cmake"

Go uses standard testing package:

func TestEndpointSend(t *testing.T) {
    ep := NewEndpoint("unix", "/tmp/test.sock")
    err := ep.Send(Message{Type: "intent"})
    if err != nil {
        t.Fatalf("Send failed: %v", err)
    }
}

Open an issue on the relevant repository with:

• Title: Clear, concise description
• Environment: OS, compiler version, board (if applicable)
• Steps to reproduce: Minimal sequence to trigger the bug
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Logs/output: Relevant error messages or build output

• Describe the use case — what problem does this solve?
• Proposed solution — how should it work?
• Alternatives considered — other approaches you thought about
• Which repo — where should this be implemented?

All contributions are made under the MIT License. By submitting a pull request, you agree that your contribution will be licensed under the same terms.

• Open a Discussion for general questions
• File an Issue for bugs or feature requests
• Check individual repo READMEs for project-specific details

Thank you for contributing to the EoS Platform! 🚀