bakar

kas-based BSP build orchestrator for Yocto. Runs kas directly on the host by default - --container opts into kas-container - and adds 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), Qualcomm (qcom), 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), Qualcomm (qcom), 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 build in one command (host by default, --container for kas-container), 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 and never deletes anything on it. For a meta-avocado kas file it checks the host's release workspace (configured under [workspaces]), pushes the checkout's commit (or a snapshot of uncommitted work) to a new ref of the host's meta-avocado clone, places it as a detached worktree, and builds there under the reuse repository policy so no shared clone is moved off its pin. Other build families keep an additive rsync -a of the workspace to the identical path, which adds and updates files and never removes one that exists only on the host. Dispatch prints what it will add and does not prompt (--yes only overrides a bakar version mismatch), 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 global --host flag forces host execution and overrides a container toggle from BAKAR_CONTAINER, the workspace .bakar.toml or the user config.toml; only --container outranks it. 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. With two or more builds live in one workspace, bakar stop refuses to guess: it lists them and asks for --run <id> on a non-interactive stdin, or offers a numbered interactive pick on a TTY. bakar ps lists the builds whose bitbake has started, plus detached or dispatched units not yet at bitbake - host and container mode, any workspace - as plain text or --json, directory-independent so it runs from anywhere. See docs/stop.md, docs/ps.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 or SSH disconnect no longer kills kas and bitbake. The scope keeps kas and bitbake running; the bakar front-end, which writes kas.log and the run record, survives a reaped background shell only under --detach (see the Detached builds bullet). 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.
• Detached builds and run status - bakar build --detach (also bakar bitbake and bakar rebuild) runs the whole pipeline in a bakar-detach-* systemd user unit, so the front-end survives a closed terminal or a reaped background shell, and prints one JSON handle line on stdout. bakar status <handle> reports the run's state and task progress, and bakar wait <handle> --timeout N blocks until it ends, exiting 0 (succeeded), 1 (failed), 3 (unknown) or 124 (timeout), and 2 when the handle does not resolve. bakar build --on <host> --detach does the same on a remote node and prints the handle with host set. See docs/build.md.
• Workspace pin repair - bakar sync <kas file> [--on HOST] [--dry-run] moves the clean, off-pin shared clones of a meta-avocado release workspace onto the commits the kas file pins, locally or on a build node, and leaves dirty clones, missing clones, side checkouts and branch pointers alone. It refuses while a build holds the workspace, writes a revert record, and bakar sync --revert FILE puts the clones back. See docs/sync.md.
• Pre-flight diagnostics - host, container and workspace checks (bakar doctor runs the full set) 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, 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. bakar sstate-seed populates and inspects a release-keyed native/cross sstate seed, the largest single build-time lever measured on this fleet (26.4 min to 9.0 min, 65% of wall-clock) - --status reports a seed built for the wrong oe-core release as stale rather than letting it silently miss. See docs/hashserv.md, docs/clean-cache.md, docs/sstate-seed.md.
• Package feed - bakar feed turns a finished build into a servable feed over one feed root: stage the RPMs, render per-machine repositories, derive the index a client reads, serve the tree over HTTP, mirror a published feed for offline builds, and prune what accumulates. See docs/feed.md.
• PR service - bakar prserv runs a workspace-scoped bitbake-prserv daemon on persistent storage, so package revisions stay monotonic across builds and a wiped build tree no longer trips the version-going-backwards QA. See docs/prserv.md.
• Distributed compile visibility - bakar cluster-info prints the sccache-dist scheduler's live capacity (servers, CPUs, jobs in flight); bakar sched-triage aggregates the scheduler journal and the client error log into one post-hoc cluster-utilisation report. See docs/cluster-info.md, docs/sched-triage.md.
• Shell and scripting - interactive/one-shot kas shell (host by default, --container for kas-container), 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.
• Native rebuild attribution - bakar insights --natives explains why native and cross recipes rebuilt in a finished run: it compares each rebuilt recipe's signature with its previous one using bitbake's own signature comparison, groups the causes across recipes, and reports what it could not explain. Every build records the signature files of executed native/cross tasks under the sstate directory, so causes stay explainable after the build directory is gone, and bakar doctor warns before a build when the bitbake/oe-core/poky revisions moved since the last recorded build. See docs/insights.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