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, so it works out of the box without Docker. The container path is an explicit opt-in: pass the global --container flag, set BAKAR_CONTAINER=1, or set a [build] container = true toggle in the workspace .bakar.toml or user config.toml. Configuring a kas_container_image does not select the container on its own - it only names the image used once the container path is opted into. The older --host flag, BAKAR_HOST_MODE, and [build] host_mode are retained as no-op back-compat aliases (host is already the default) so existing configs keep working. Precedence: --container > --host > BAKAR_CONTAINER > workspace container > user container > host.
• 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 - 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. By default the scope also sets a positive oom_score_adjust (the build is the OOM victim under global pressure); it does not impose memory ceilings or CPU/IO weights, so memory and scheduling behave exactly as they did before the scope. CPUWeight/IOWeight ([build] scope_cpu_weight/scope_io_weight) are opt-in and off by default: setting them realizes the cpu/io cgroup controllers session-wide, and under a heavy-I/O recipe the io controller's throttling can hang the whole session (observed with chromium). Hard cgroup memory caps (MemoryHigh/MemoryMax, plus MemorySwapMax=0) are opt-in under [build] scope_memory_* for dedicated build hosts - on a workstation with a large zram swap they swap-thrash the desktop and can soft-lock the box, so they default off. Parallelism (BB_NUMBER_THREADS/PARALLEL_MAKE) is never touched. Opt out of scoping entirely with --no-scope. 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. With [build] uninative = true, seven further checks verify the host uninative tarball's wiring: that its fragment is actually installed (the overlay gate drops the wiring silently when it is not), that its glibc ceiling covers the buildtools sysroot that links every native binary, that its mirrored payload matches the checksum it declares, that no DL_DIR cache entry holds a dangling payload link, and - in cluster mode - that every node resolved the same ceiling. bakar doctor --post-build adds a scan of a finished build's native work tree for glibc version nodes above that ceiling. 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 or variable flag (getvar, getvar --flag, writing the resolved value to stdout and all diagnostics to stderr so v=$(bakar getvar ...) works), 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