ebuild — Unified Embedded Build System

ebuild is a unified embedded build system written in Python. You describe a project in a single build.yaml; ebuild resolves the dependency and toolchain graph and drives an underlying build backend, then extends into firmware and system-image workflows for embedded targets. It is part of the EmbeddedOS (EoS) ecosystem. (ebuild here is the EoS build tool and is unrelated to Gentoo's ebuild format.)

⚡ Quick Demo

New here? See demo.md — a 5-minute, self-contained walkthrough that lists the prerequisites (Python, gcc, and the ninja pip package), then builds and runs a tiny "thermostat" C program end-to-end via ebuild build. A troubleshooting appendix covers no-root / PEP 668 environments and building without a system compiler.

Features

Observed in the source tree:

• Backend dispatch — auto-detects the project's build system and dispatches to CMake, Make, Meson, Cargo, or Kbuild, or generates a Ninja build (ebuild/build/dispatch.py, ebuild/build/ninja_backend.py). Per the package metadata, its target scope also includes Buildroot, Zephyr, FreeRTOS, and NuttX.
• Package graph — install and list project packages (ebuild add, ebuild list-packages).
• Firmware & flashing — build RTOS firmware and flash images to targets (ebuild firmware, ebuild flash; ebuild/firmware/).
• System images — root filesystem, kernel, and disk-image assembly (ebuild system; ebuild/system/).
• Project scaffolding — generate projects and boards from templates (ebuild new, ebuild generate-project, ebuild generate-board, ebuild generate-boot).
• Layers & recipes — reusable board/OS composition under layers/ and ebuild/recipes/.

What's inside

Path	Contents
ebuild/	The Python package: cli/, build/, core/, system/, firmware/, deps/, packages/, plugins/, eos_ai/
core/	Native support components (e.g. eboot/)
examples/	hello_world, linux_image, multi_target, rtos_firmware, cortex_r5_safety, eradar360, with_packages
ebuild/templates/	Project templates used by ebuild new / ebuild init (shipped in the wheel)
ebuild/recipes/, layers/	Reusable build recipes and board/OS layers
hardware/	Board/hardware definitions
sdk/	SDK generation support
tools/	Helper scripts
docs/	Documentation (published with MkDocs)

Install

Requires Python 3.8+.

Building a static_library target also invokes that Python interpreter at build time: the generated Ninja ar_rule runs a small helper to recreate the archive so removed object members cannot linger.

pip install -e .        # from the repo root
# or:
./install.sh            # puts the 'ebuild' command on your PATH
./install.sh --check    # verify the installation

Runtime dependencies (click, pyyaml, ninja) are installed automatically. ebuild prefers a ninja binary on PATH and falls back to python -m ninja if none is present, so a system ninja install is enough. The pip ninja package is the fallback when no binary is on PATH.

Usage

ebuild info             # show what ebuild parsed from build.yaml
ebuild build            # resolve and build (auto-detects the backend)
ebuild test             # run the project's tests
ebuild build -j 4       # build independent packages concurrently
ebuild clean            # remove build artifacts
ebuild --version

-j/--jobs controls how many packages are built at once. Dependency order is always honoured — a package starts only once everything it depends on has finished — so -j only overlaps packages that are genuinely independent of one another. It defaults to 1, which builds strictly in dependency order. Note that each package's own build may already run parallel compile jobs, so a large -j can oversubscribe the machine. See docs/dependency-management.md.

Additional commands: configure, install, add, list-packages, search, update-index, pipeline, system, firmware, flash, new, generate-project, generate-board, generate-boot, analyze, setup, and the repos group (status, update, set-url, set-branch, link, unlink). Run ebuild --help for the full list.

ebuild test reports the counts the underlying runner printed, and reports none when it printed nothing recognisable — a number inferred from a zero exit status is a guess presented as a measurement.

It also treats a run that executed no tests as a failure. ctest exits 0 when it finds nothing to run, and a CMakeLists.txt with enable_testing() and no add_test() still produces a CTestTestfile.cmake — so the runner is found, ctest prints No tests were found!!!, and trusting the exit status would report a green suite for a project with no tests at all.

Projects that declare type: test targets in build.yaml are built and run directly (no ctest/cargo/meson). On Windows those binaries are named <target>.exe, matching the Ninja edge; ebuild test now asks ninja for that path rather than the unsuffixed name.

Test

pip install -e ".[dev]"
pytest                  # configuration in pytest.ini

Documentation

Docs live under docs/ and are published with MkDocs (mkdocs.yml): https://embeddedos-org.github.io/ebuild/.

License

MIT — see LICENSE.

Part of embeddedos-org.