Metadata-Version: 2.4
Name: bakar
Version: 0.26.0
Summary: kas-based Yocto BSP build orchestrator - live build UI, pre-flight checks, telemetry, and failure triage
Keywords: bitbake,bsp,embedded,imx,kas,nxp,ti-sitara,yocto
Author: Javier Tia
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Operating System Kernels :: Linux
Requires-Dist: networkx>=3.0
Requires-Dist: pydot>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12.0
Requires-Python: >=3.14
Project-URL: Bug Tracker, https://github.com/jetm/bakar/issues
Project-URL: Homepage, https://github.com/jetm/bakar
Project-URL: Repository, https://github.com/jetm/bakar
Description-Content-Type: text/markdown

# bakar

[![CI](https://github.com/jetm/bakar/actions/workflows/ci.yml/badge.svg)](https://github.com/jetm/bakar/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/bakar)](https://pypi.org/project/bakar/)
[![Python](https://img.shields.io/pypi/pyversions/bakar)](https://pypi.org/project/bakar/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Coverage](https://img.shields.io/codecov/c/github/jetm/bakar)](https://codecov.io/gh/jetm/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.

![bakar build UI](docs/build-ui.gif)

## 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](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/build.md), [docs/sync.md](docs/sync.md), [docs/gen-kas.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](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](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/build.md), [docs/config-reference.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/doctor.md), [docs/settings.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/triage.md), [docs/report.md](docs/report.md), [docs/insights.md](docs/insights.md), [docs/log.md](docs/log.md), [docs/monitor.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/lock.md), [docs/diff.md](docs/diff.md), [docs/drift.md](docs/drift.md), [docs/changelog.md](docs/changelog.md), [docs/dump.md](docs/dump.md), [docs/prefetch.md](docs/prefetch.md), [docs/mirror.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/bitbake.md), [docs/graph.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/hashserv.md), [docs/clean-cache.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/shell.md), [docs/for-all.md](docs/for-all.md), [docs/run.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](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](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/settings.md), [docs/configuration.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/bitbake-override.md), [docs/stress-parse.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](docs/setup.md).
- **Workspace scaffolding** - `init` wizard (interactive or `--family`) writes `.bakar.toml`. See [docs/init.md](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/getvar.md), [docs/show.md](docs/show.md), [docs/layers.md](docs/layers.md), [docs/inspect.md](docs/inspect.md), [docs/diffsigs.md](docs/diffsigs.md).

## Install

```bash
uv tool install bakar
# or
pip install bakar
```

## Quickstart

```bash
# 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](docs/index.md)**
