ebuild Developer Documentation v0.1.0

Unified build system and SDK manager for EmbeddedOS. Handles project scaffolding, cross-compilation, flashing, serial monitoring, testing, and SDK component management across all supported platforms — from bare-metal MCUs to desktops, TVs, tablets, and any device.

Smart Dependency Resolution

ebuild automatically resolves all dependencies based on the target platform and the products you include. Building for desktop with EoStudio? ebuild pulls in Python 3.10+, OpenGL 3.3+, and GUI frameworks. Building for an MCU? It fetches the bare-metal toolchain. You declare what you want — ebuild figures out everything else.

📦 Installation

# Install from Go source
go install github.com/embeddedos-org/ebuild@latest

# Or download pre-built binary
curl -L https://github.com/embeddedos-org/ebuild/releases/latest/download/ebuild-linux-amd64 \
  -o /usr/local/bin/ebuild && chmod +x /usr/local/bin/ebuild

# Verify installation
ebuild --version
# ebuild v0.3.0 (EmbeddedOS Build System)

📄 ebuild init

ebuild init <project-name> [options]

Scaffold a new EmbeddedOS project with directory structure, build.yaml, main.c, linker scripts, and Makefile for the target platform.

Options

`--platform <name>`	`string`	Target: stm32f4, esp32, nrf52, raspi4, desktop, tv, tablet, laptop, kiosk, linux. Default: linux.
`--template <type>`	`string`	bare (minimal), rtos (kernel), ai (EAI), full (all modules).
`--with-eboot`	`flag`	Include eBoot bootloader configuration.
`--with-eai`	`flag`	Include EAI agent framework.
`--with-eni`	`flag`	Include ENI neural interface.
`--with-eostudio`	`flag`	Include EoStudio (desktop/tablet only, auto-pulls Python, OpenGL).
`--with-eapps`	`flag`	Include eApps suite.

Example — Embedded

$ ebuild init my-robot --platform stm32f4 --template rtos --with-eai

Creating project: my-robot
  Platform: stm32f4 (ARM Cortex-M4F, 168MHz, 1MB Flash, 192KB RAM)
  Template: rtos (EoS kernel + HAL)
  Modules:  eai

Created:
  my-robot/
  ├── build.yaml
  ├── src/main.c
  ├── include/app_config.h
  ├── linker/stm32f407.ld
  ├── eai/agent_config.yml
  └── Makefile

Run: cd my-robot && ebuild build

Example — Desktop with EoStudio

$ ebuild init my-workstation --platform desktop --with-eostudio --with-eapps

Creating project: my-workstation
  Platform: desktop (x86_64, Full GUI)
  Modules:  eostudio, eapps, eai

Resolving dependencies...
  ✓ Python 3.10+     (runtime for EoStudio)
  ✓ OpenGL 3.3+      (GPU rendering)
  ✓ LVGL             (UI framework for eApps)
  ✓ Mesa/GPU drivers (display backend)
  ✓ Wayland/X11      (window system)
  ✓ audio stack      (media support)

Created:
  my-workstation/
  ├── build.yaml
  ├── src/main.c
  ├── include/app_config.h
  ├── eostudio/config.yml
  ├── eapps/manifest.yml
  └── Makefile

Run: cd my-workstation && ebuild build

Example — Smart TV

$ ebuild init my-tv --platform tv --with-eapps

Creating project: my-tv
  Platform: tv (ARM64, 4K UI)
  Modules:  eapps, eni

Resolving dependencies...
  ✓ LVGL             (4K UI framework)
  ✓ GPU drivers      (hardware rendering)
  ✓ HDMI/CEC         (display + remote control)
  ✓ media codecs     (H.264/H.265/AV1)
  ✓ audio stack      (surround sound)

Run: cd my-tv && ebuild build

🔧 ebuild build

ebuild build [options]

Cross-compile the project. Reads build.yaml for platform, toolchain, and modules. Outputs ELF, BIN, and HEX.

Options

`--release`	`flag`	Build with -O2 and LTO. Default: debug (-Og -g).
`--verbose`	`flag`	Show compiler commands.
`--jobs <N>`	`int`	Parallel jobs. Default: CPU count.
`--define <K=V>`	`string`	Add preprocessor define (repeatable).
`--target <name>`	`string`	Build specific target from build.yaml.

Example

$ ebuild build --release --verbose

[ebuild] Platform: stm32f4 (arm-none-eabi-gcc 13.2)
[CC] src/main.c
[CC] eos/hal/src/hal_stm32.c
[CC] eos/kernel/src/kernel.c
[LD] build/release/my-robot.elf
[BIN] build/release/my-robot.bin (142,336 bytes)

Build complete: 0.8s (4 modules, 23 files)
  Flash: 139 KB / 1024 KB (13.6%)
  RAM:   42 KB / 192 KB (21.9%)

⚡ ebuild flash

ebuild flash [options]

Flash firmware to the target device. Auto-detects debug probe (ST-Link, J-Link, CMSIS-DAP). Supports eBoot A/B slot targeting.

Options

`--probe <type>`	`string`	Force probe: stlink, jlink, cmsis-dap, openocd.
`--slot <A\|B>`	`string`	Target eBoot slot (default: inactive slot).
`--verify`	`flag`	Verify flash after writing.
`--reset`	`flag`	Reset target after flash. Default: true.
`--binary <path>`	`string`	Flash specific binary (default: last build output).

Example

$ ebuild flash --verify
[ebuild] Detected: ST-Link V2 (serial: 066DFF343...)
[ebuild] Target: STM32F407VG
[flash] Erasing sectors 0-5...
[flash] Writing build/release/my-robot.bin (142,336 bytes)
[flash] Verifying... OK
[flash] Resetting target...
Flash complete in 2.3s

💻 ebuild monitor

ebuild monitor [options]

Open serial monitor for UART output. Supports log coloring, timestamps, and level filtering.

Options

`--port <path>`	`string`	Serial port (auto-detected if omitted).
`--baud <rate>`	`int`	Baud rate. Default: 115200.
`--filter <level>`	`string`	Min log level: TRACE, DEBUG, INFO, WARN, ERROR.
`--log <file>`	`string`	Save output to file.
`--timestamp`	`flag`	Prefix lines with host timestamp.

Example

$ ebuild monitor --filter INFO --timestamp
[ebuild] Port: /dev/ttyACM0 @ 115200
--- EoS Serial Monitor (Ctrl+C to exit) ---
[14:23:01.234] [INFO]  kernel: EoS v0.1.0 starting on STM32F407
[14:23:01.238] [INFO]  hal: GPIO, UART, SPI, I2C initialized
[14:23:01.240] [INFO]  power: Battery 87%, 3.92V
[14:23:01.245] [INFO]  eai: TinyLlama-1.1B loaded (680MB RAM)
[14:23:01.300] [INFO]  app: System ready

✅ ebuild test

ebuild test [options]

Run unit tests. Builds for host (x86/ARM Linux) and executes, or runs on-target via debug probe.

Options

`--on-target`	`flag`	Run tests on physical hardware.
`--coverage`	`flag`	Generate code coverage report.
`--filter <pat>`	`string`	Run matching tests only.
`--xml <path>`	`string`	Output JUnit XML report.

Example

$ ebuild test --coverage
[test] Building for host (x86_64-linux-gnu)
[test] Running 47 tests...
  ✓ test_gpio_init (0.1ms)
  ✓ test_uart_loopback (1.3ms)
  ✓ test_kernel_task_create (0.5ms)
  ... (44 more)
[test] 47/47 passed (0 failed, 0 skipped)
[coverage] Line coverage: 78.3% (1,247/1,593)

🗑 ebuild clean

ebuild clean [--all]

Remove build artifacts. --all also removes downloaded SDK components and toolchains.

📁 SDK Structure

$HOME/.ebuild/
├── toolchains/
│   ├── arm-none-eabi-gcc-13.2/
│   ├── riscv64-unknown-elf-gcc-13/
│   └── xtensa-esp32-elf-gcc-12/
├── sdks/
│   ├── eos/       # EoS kernel + HAL + modules
│   ├── eboot/     # eBoot bootloader
│   ├── eai/       # EAI framework
│   ├── eni/       # ENI neural interface
│   └── eipc/      # EIPC protocol SDK
├── platforms/
│   ├── stm32f4/   # Platform support packages
│   ├── esp32/
│   └── nrf52/
└── cache/         # Downloaded archives

📜 build.yaml Reference

# build.yaml - EmbeddedOS project configuration
project:
  name: my-robot
  version: 1.0.0

platform:
  name: stm32f4
  mcu: STM32F407VG
  clock_hz: 168000000
  flash_size: 1048576    # 1MB
  ram_size: 196608       # 192KB

toolchain:
  compiler: arm-none-eabi-gcc
  version: ">=13.0"
  c_standard: c11
  optimization: -Og
  warnings: [-Wall, -Wextra, -Werror]
  defines:
    - EOS_ENABLE_POWER=1
    - EOS_ENABLE_NET=0
    - EOS_MAX_TASKS=16

modules:
  - kernel    # RTOS kernel
  - hal       # Hardware abstraction
  - power     # Power management
  - eai       # Embedded AI (optional)

eboot:
  enabled: true
  max_attempts: 3
  slot_size: 0x40000     # 256KB per slot

sources:
  - src/**/*.c
  - drivers/**/*.c

include_dirs:
  - include/
  - config/

linker:
  script: linker/stm32f407.ld
  libs: [-lm, -lnosys]

flash:
  probe: auto
  address: 0x08020000   # Slot A start

monitor:
  port: auto
  baud: 115200

🌎 Supported Platforms

Platform	Arch	MCU/SoC	Flash	RAM	Toolchain
Embedded & MCU
stm32f4	Cortex-M4F	STM32F407VG	1MB	192KB	arm-none-eabi-gcc
stm32h7	Cortex-M7	STM32H743ZI	2MB	1MB	arm-none-eabi-gcc
nrf52	Cortex-M4F	nRF52840	1MB	256KB	arm-none-eabi-gcc
nrf5340	Cortex-M33	nRF5340	1MB	512KB	arm-none-eabi-gcc
esp32	Xtensa LX6	ESP32	4MB	520KB	xtensa-esp32-elf
k64f	Cortex-M4F	MK64FN1M0	1MB	256KB	arm-none-eabi-gcc
Application Processors
raspi4	Cortex-A72	BCM2711	SD	1-8GB	aarch64-linux-gnu
imx8m	Cortex-A53	i.MX8M Mini	eMMC	1-4GB	aarch64-linux-gnu
Desktop, TV & Multi-Platform
desktop	x86_64 / ARM64	PC / Mac	SSD/NVMe	4-64GB	gcc/clang + Python, OpenGL, GUI
laptop	x86_64 / ARM64	Laptop SoC	SSD	4-32GB	gcc/clang + battery, GUI
tv	ARM64 / x86_64	Smart TV SoC	eMMC	2-8GB	gcc/clang + HDMI, 4K, media
tablet	ARM64	Tablet SoC	eMMC	2-8GB	aarch64-gnu + touch, stylus
kiosk	x86 / ARM	Kiosk SoC	eMMC/SSD	2-8GB	gcc/clang + touchscreen, single-app
linux	x86_64/aarch64	Host	N/A	N/A	gcc/clang

ebuild auto-downloads required toolchains, SDK components, and all platform-specific packages on first use. For desktop/TV platforms, this includes runtimes (Python), GPU drivers (OpenGL/Vulkan), window systems (Wayland/X11), media codecs, and more. Set EBUILD_HOME to change install directory (default: ~/.ebuild).

📦 ebuild deps

ebuild deps <command> [options]

Manage platform and product dependencies. ebuild automatically resolves what packages are needed based on the target platform and included products.

Subcommands

`deps resolve`	Analyze build.yaml and resolve all required packages for the target platform.
`deps list`	List all resolved dependencies and their versions.
`deps install`	Download and install all resolved dependencies.
`deps check`	Verify all dependencies are satisfied.
`deps tree`	Show full dependency tree including transitive dependencies.

Example — Desktop with EoStudio

$ ebuild deps resolve
[deps] Platform: desktop (x86_64)
[deps] Products: eostudio, eapps, eai

Resolved dependencies:
  ┌─ EoStudio
  │  ├─ python >=3.10       (runtime)
  │  ├─ opengl >=3.3        (GPU rendering)
  │  ├─ pip packages         (numpy, pillow, pyopengl)
  │  └─ mesa-drivers         (GPU backend)
  ├─ eApps
  │  ├─ lvgl                 (UI framework)
  │  ├─ wayland / x11        (window system)
  │  └─ audio-stack          (PulseAudio/PipeWire)
  ├─ EAI
  │  ├─ onnxruntime          (inference)
  │  └─ libcurl              (model download)
  └─ EoS Kernel
     ├─ gcc/clang            (compiler)
     ├─ glibc                (C library)
     └─ linux-headers        (kernel interface)

Total: 23 packages (412 MB)

$ ebuild deps install
[deps] Installing 23 packages...
[deps] ✓ python-3.12.1     installed
[deps] ✓ opengl-4.6        installed
[deps] ✓ lvgl-9.1          installed
[deps] ... (20 more)
[deps] All dependencies satisfied.

Example — Embedded (minimal)

$ ebuild deps resolve
[deps] Platform: stm32f4 (ARM Cortex-M4F)
[deps] Products: kernel, hal, eai

Resolved dependencies:
  ├─ arm-none-eabi-gcc 13.2  (cross-compiler)
  ├─ newlib                   (embedded C library)
  └─ cmsis                    (ARM headers)

Total: 3 packages (560 MB)

🔌 ebuild sdk

ebuild sdk <command> [options]

Manage EoS SDK components. Download, update, remove, and list installed SDK modules and toolchains.

Subcommands

`sdk install <module>`	Install SDK module: kernel, hal, eai, eni, eipc, eboot.
`sdk update [module]`	Update all or specific module to latest version.
`sdk remove <module>`	Remove installed module.
`sdk list`	List installed modules with versions.
`sdk toolchain install <name>`	Install toolchain (arm-none-eabi-gcc, riscv64-elf-gcc).
`sdk toolchain list`	List installed toolchains.

Example

$ ebuild sdk install eai
[sdk] Downloading EAI v0.1.0 (2.3 MB)...
[sdk] Installing to ~/.ebuild/sdks/eai/
[sdk] Done. EAI framework ready.

$ ebuild sdk list
Installed SDK modules:
  kernel  v0.1.0  (installed 2026-03-15)
  hal     v0.1.0  (installed 2026-03-15)
  eai     v0.1.0  (installed 2026-03-31)
  eboot   v0.1.0  (installed 2026-03-15)

$ ebuild sdk toolchain list
Installed toolchains:
  arm-none-eabi-gcc  13.2.1  (560 MB)
  riscv64-elf-gcc    13.2.0  (420 MB)

📄 ebuild generate

ebuild generate <type> <name> [options]

Generate boilerplate code for common patterns.

Types

`generate driver <name>`	Generate driver skeleton (probe, remove, suspend, resume, ioctl).
`generate service <name>`	Generate service skeleton (start, stop, health).
`generate tool <name>`	Generate EAI tool skeleton with params and exec callback.
`generate provider <name>`	Generate ENI provider skeleton (init, poll, start, stop).
`generate test <module>`	Generate unit test file for a module.

Example

$ ebuild generate driver bme280
[gen] Created: drivers/bme280/bme280.c
[gen] Created: drivers/bme280/bme280.h
[gen] Created: drivers/bme280/Makefile
[gen] Added to build.yaml sources

$ ebuild generate tool temperature_read
[gen] Created: tools/temperature_read.c
[gen] Created: tools/temperature_read.h
[gen] Tool registered in tools/registry.c

📊 ebuild info

ebuild info [platform]

Display project or platform information: target MCU specs, memory map, peripheral list, toolchain version, SDK versions.

Example

$ ebuild info
Project: my-robot v1.0.0
Platform: stm32f4 (STM32F407VG)
  CPU:    ARM Cortex-M4F @ 168MHz (FPU, MPU)
  Flash:  1024 KB (0x08000000 - 0x080FFFFF)
  RAM:    192 KB  (0x20000000 - 0x2002FFFF)
  CCM:    64 KB   (0x10000000 - 0x1000FFFF)
Toolchain: arm-none-eabi-gcc 13.2.1
SDK:
  kernel v0.1.0, hal v0.1.0, eai v0.1.0
Modules: kernel, hal, power, eai
eBoot: enabled (max_attempts=3, slot_size=256KB)

🔄 ebuild ota

ebuild ota <command> [options]

Over-the-air firmware update management. Build, sign, and deploy OTA packages to devices.

Subcommands

`ota package`	Build OTA package (.eos_fw) with header, CRC, and optional signature.
`ota push <host>`	Push OTA package to device via HTTP/MQTT.
`ota status <host>`	Check OTA status on device (active slot, pending, version).
`ota rollback <host>`	Force rollback to confirmed slot.

Example

$ ebuild ota package --sign key.pem
[ota] Building OTA package...
[ota] Image: build/release/my-robot.bin (142,336 bytes)
[ota] CRC32: 0xA3B7C1D2
[ota] Signed with key.pem (RSA-2048)
[ota] Package: build/my-robot-v1.0.0.eos_fw (142,512 bytes)

$ ebuild ota push 192.168.1.100
[ota] Uploading to 192.168.1.100:8420...
[ota] Progress: 100% (142,512 bytes)
[ota] Device: installing to slot B...
[ota] Device: rebooting into test boot...
[ota] Device: boot confirmed! OTA success.