bakar 0.23.0

kas-based Yocto BSP build orchestrator - live build UI, pre-flight checks, telemetry, and failure triage

bakar

kas-based BSP build orchestrator for Yocto. Wraps kas-container with manifest-driven sync, pre-flight checks, a live event-driven build UI, structured telemetry, and post-mortem tooling. Works with NXP i.MX (repo XML), TI Sitara (oe-layertool), bitbake-setup workspaces, and any bring-your-own kas YAML.

Features

• Multi-BSP, out of the box - NXP i.MX (repo XML), TI Sitara (oe-layertool), bitbake-setup workspaces, meta-avocado, and any bring-your-own kas YAML, with automatic family detection. See docs/workspace.md.
• Idempotent build pipeline - doctor -> sync -> gen-kas -> kas-container build in one command, with dry-run, --dry-run-script (emit a runnable shell script for the full invocation), keep-going, and from-scratch rebuild. See docs/build.md, docs/sync.md, docs/gen-kas.md.
• Remote build dispatch - bakar build --on <host> runs a build on an idle remote node in one command: it preflights the ssh host, rsyncs the working tree (uncommitted edits included) to the identical path with a cache/artifact exclude set, gates the destructive --delete mirror behind a dry-run preview and confirmation (--yes bypasses it), execs bakar build remotely fish-safely over ssh <host> bash -s with sccache-dist off by default (--sccache-dist opts back in), streams the build output live, and surfaces the remote run-id plus a copy-pasteable ssh <host> bakar triage <run-id> line. The remote exit code propagates. See docs/build.md.
• Host execution by default - bakar runs kas directly on the host when no container image is configured, so it works out of the box without Docker. The container path stays opt-in: configure a kas_container_image (env KAS_CONTAINER_IMAGE, workspace [build], or user config.toml) and bakar uses kas-container. An explicit [build] host_mode = true (env BAKAR_HOST_MODE, or --host) forces host mode even when an image is configured; it only ever forces host on. Precedence: --host > BAKAR_HOST_MODE > workspace host_mode > user host_mode > auto-detect (host when no image configured).
• Graceful build stop - bakar stop halts a running build by routing SIGINT to bitbake's own shutdown (then escalating to SIGTERM/SIGKILL, or --force to skip the grace period). Container builds are signalled inside the container, targeted by a per-run bakar.run_id label; host builds by their recorded process group - so other workspaces and the persistent hashserv daemon are never touched. The build stays resumable with no manual cleansstate, and bakar build warns when a prior build was killed uncleanly. See docs/stop.md.
• Session-survival and containment - bakar build (and the live bakar bitbake path) run kas/kas-container inside a transient systemd-run --user --scope by default, so a closed terminal, SSH disconnect, or reaped background shell no longer kills the build, and a runaway is bounded by cgroup resource controls: a MemoryMax hard ceiling below total RAM (a memory blow-up OOM-kills the build cgroup instead of the whole box), a MemoryHigh soft throttle, a positive oom_score_adjust so the build is the OOM victim under global pressure, and below-default CPUWeight/IOWeight to keep the host responsive. Parallelism (BB_NUMBER_THREADS/PARALLEL_MAKE) is left untouched. All limits are configurable under [build] scope*; opt out with --no-scope. This hardens survival and containment only - it does not address filesystem/kernel faults. See docs/build.md, docs/config-reference.md.
• Pre-flight diagnostics - ~30 host/container/workspace checks with PASS/WARN/BLOCK gating and PSI throttle calibration. Checks always run before a build or sync; the global --hide-doctor-report flag (or build.show_doctor_report = false) hides the report while still aborting on a blocking issue. The host-environment thresholds (inotify instances/watches, swappiness ceiling, docker nofile floor, minimum memory) are configurable via host.* settings keys; defaults equal the values doctor previously hardcoded. See docs/doctor.md, docs/settings.md.
• Live build UI - driven by bitbake's own structured event stream (with a knotty-text fallback): a parse → setscene → tasks pipeline header with per-stage durations and a global wall clock, an sstate reuse ratio ("92% sstate (412 cached, 38 will build)"), a parse cache efficiency note, and a per-task table with task-type icons. Stuck-task highlighting compares each recipe against per-recipe timing baselines accumulated across builds, not just the current run's median. On a task failure the build status freezes above the error text and a ✗ FAILED alert carries the host-side log path plus the last lines of the task log. Assumes a truecolor terminal and a Nerd Font.
• Observability and post-mortem - per-run telemetry (events.jsonl, logs, timing, disk usage) plus a normalized bitbake event stream (bitbake-events.json) parsed from bitbake's own event log on every build. bakar triage reads that artifact to name the failing recipe/task and print the recorded logfile excerpt (with a kas.log fallback for older runs), and selects the right run dir under a multi-release preset fan-out via --run/--preset/--release. bakar monitor watches a running build in one view - sccache-dist cluster load, build-daemon cache/dist stats, and bitbake task progress - as a refreshing terminal UI or as --json/NDJSON for CI. bakar insights renders per-recipe/per-task analytics for a completed run - sstate hit/miss breakdown, per-task timing with top-N slowest, PSI CPU/IO/memory pressure share, and disk-usage growth - defaulting to the latest run under the workspace, same as report. See docs/triage.md, docs/report.md, docs/insights.md, docs/log.md, docs/monitor.md.
• Reproducibility - pin floating layer SHAs, diff manifests/configs, detect workspace drift (bakar drift), generate release notes between pinned states (bakar changelog), flatten the resolved kas YAML, pre-fetch sources for offline builds, and seed a host-side premirror git2_*.tar.gz tarball from a git URL. See docs/lock.md, docs/diff.md, docs/drift.md, docs/changelog.md, docs/dump.md, docs/prefetch.md, docs/mirror.md.
• Recipe operations - run one recipe or task through bakar bitbake (logged, exit-code-faithful), clean a single recipe's sstate with bakar clean-recipe, rebuild one from scratch (cleansstate then build) with bakar rebuild, and analyze a recipe's dependency graph (blast radius, longest chain, cycles) with bakar graph. See docs/bitbake.md, docs/graph.md.
• Build performance and robustness - ccache (per-workspace or shared), NPROC-scaled parallelism, PSI throttling with ratchet-up autocalibration, curated mirrors, persistent hash-equivalence server, and age-based sstate/ccache pruning. See docs/hashserv.md, docs/clean-cache.md.
• Shell and scripting - interactive/one-shot kas-container shell, run a command in every source repo, boot a QEMU image from the build dir. See docs/shell.md, docs/for-all.md, docs/run.md.
• Named presets - name a full build configuration in config.toml and invoke it with bakar build --preset <name>; multi-release presets fan out to N sequential builds with a summary table. Manage presets with bakar presets list/show/add/remove. See docs/presets.md.
• Shell completion - tab-completion for all subcommands, flags, and preset names. bash and zsh via bakar --install-completion; fish via a generator script. See docs/completion.md.
• Layered configuration - CLI > BAKAR_* env > workspace .bakar.toml > preset > user config.toml > BSP default, plus a settings CRUD interface and a vendor config layer for custom board families. See docs/settings.md, docs/configuration.md.
• Advanced tooling - swap the BSP-bundled bitbake for a local upstream checkout, and stress-test the bitbake parser fork race. See docs/bitbake-override.md, docs/stress-parse.md.
• Host preparation - setup runs once per machine before your first build: it profiles the host, remediates the host-environment doctor checks (sysctl drop-in, docker daemon.json ulimits/storage-driver, kas install, git identity, cache dirs), applies privileged steps through a single confirmed sudo of an auditable script, and persists the applied values to the global [host] config. When host mode is the effective default, it also installs the buildtools-extended toolchain (when missing) and persists its path as [build] buildtools_dir, so bakar --host build is turnkey; container-only setups skip this. --dry-run shows the plan and script without touching anything. See docs/setup.md.
• Workspace scaffolding - init wizard (interactive or --family) writes .bakar.toml. See docs/init.md.
• Read-only inspection - query any BitBake variable (getvar), dump resolved build metadata (show), inspect layer stack and override precedence (layers inspect/status), compare task signatures across builds (diffsigs), and walk the full recipe environment (inspect). See docs/getvar.md, docs/show.md, docs/layers.md, docs/inspect.md, docs/diffsigs.md.

Install

uv tool install bakar
# or
pip install bakar

Quickstart

# First time on this machine: prepare the host (sysctl, docker, kas, git identity)
bakar setup

# NXP i.MX manifest-driven build
bakar build -f imx-6.12.49-2.2.0.xml -m imx8mp-var-dart

# Bring-your-own kas YAML
bakar build my-project.yml

# Post-mortem a failed build
bakar triage

Documentation

Full command reference, workflow guides, and configuration: docs/index.md