Development
Repo layout
| Path | Content |
|---|---|
src/main.py | Entry point; signal handlers stop running containers on Ctrl-C. |
src/commands/__init__.py | Command tree engine: nested dict (_help, _handler, _args) → argparse subparsers; unique-prefix abbreviation; version-mismatch dispatch. |
src/commands/common/ | create, gui, login/logout, upgrade, info project/secrets, configure project. |
src/commands/hive_s/, src/commands/hive_m/ | Template command sets. |
src/commands/app/ | app init (common), app build/sign/license (only with buildhive-app.json). |
src/commands/hive_m/common/__init__.py | Init script prepended to every hive-m container run. |
src/project.py | Project load/save/create, Docker image build, container/volume orchestration. |
src/state.py | Docker client plus the running container/process handles the Ctrl-C handler stops. |
src/common.py | Template copy, hash manifest, baseline, smart_update (3-way merge). |
src/models/ | Pydantic models for project.json, buildhive-app.json and the uwm app manifest. |
src/validate.py | Argument validation: project names, module names, file paths. |
src/log.py | Console output with the INFO:/WARNING:/ERROR:/OK: prefixes the GUI colors by. |
src/vault.py | Secrets server client: OIDC login, token cache, secret lookup. |
src/signing.py | Buildsign client. Purposes update and license, each with its own message prefix. |
src/uwm_app.py | App repos: SDK container build, bundle and update package, license payload and check. |
src/selfupdate.py | Release lookup on GitHub, installer download and start (upgrade, GUI update button). |
src/constants.py | VERSION, container constants, SECRETS_URL, SDK_IMAGE. |
src/changelog.py, CHANGELOG.md | Release notes, one ## <x.y.z> section per version. Bundled into the exe for the GUI What's new dialog. |
src/templates/ | default (shared skeleton), hive-s/<release>, hive-m/<release> project templates, one directory per shipped release (ntl-v2026.1). |
src/gui/ | PySide6 GUI, see gui.md. |
src/layerconf.py, src/recipe_index.py, src/scripts/recipe_indexer.py | IMAGE_INSTALL:append editing and the recipe index (packages commands). recipe_indexer.py is shipped as a data file and run with python3 inside the container. |
tests/ | pytest suite, no Docker needed: uv run pytest. |
src/scripts/ | Everything that runs inside the containers. Bind-mounted read-only at /opt/buildhive; a command is docker run ... bash /opt/buildhive/<script> with its parameters in a --env-file. lib.sh (errexit, bh_t/bh_install/bh_own), hive-m/init.sh (repo sync, build env, layer sync, local.conf blocks; reads BUILDHIVE_* from src/commands/hive_m/common/__init__.py get_init_env()), one hive-m/*.sh per command, hive-s/*.sh likewise. tests/test_scripts.py runs bash -n on all of them, shellcheck when installed. |
src/scripts/bitbake_ui.py | BitBake UI module (bb.ui.buildhive): knotty's TerminalFilter replaced by one that prints @@BH {json} progress lines. hive-m/init.sh copies it into bitbake/lib/bb/ui/ and sets BITBAKE_UI=buildhive when BUILDHIVE_PROGRESS=json (the GUI runner sets it). Parsed by src/gui/runner.py parse_progress(). |
tools/gui_screenshots.py | Renders docs/images/gui/*.png for the GUI docs. |
tools/make_icons.py | Renders assets/app.ico, assets/logo.png and the docs logo copies from assets/logo.svg. |
tools/make_sbom.py | Writes assets/sbom.json (CycloneDX 1.5) from the runtime packages installed in the venv. Runs in make build. |
tools/release_notes.py | Prints the CHANGELOG.md section of a release tag. Used by the release workflow. |
assets/ | Logo sources (logo.svg, logo-wordmark.svg) generated app.ico (exe, window and sidebar icon) and sbom.json (About page). |
docs/ | mdBook sources (book.toml, SUMMARY.md), published to GitHub Pages. |
pyproject.toml, uv.lock, .python-version | Dependencies (runtime in [project], tools in the dev group), lockfile, interpreter version for uv. |
buildhive.spec | PyInstaller spec, one analysis, two exes (buildhive.exe, buildhive-gui.exe). |
setup.iss | Inno Setup installer script. |
dist/ | PyInstaller output + BuildHive_Setup.exe. Not committed. |
Setup
uv manages the interpreter and the venv, the system Python is not used:
uv sync # installs Python 3.14 (.python-version) + .venv from uv.lock
uv run python src/main.py # CLI / GUI from the checkout
uv run pytest
Dependencies live in pyproject.toml. uv add <pkg> / uv add --dev <pkg> update it and uv.lock; commit both. uv lock --upgrade bumps everything within the declared ranges. Without uv: uv export --format requirements-txt on a machine that has it.
Release process
Three versions, three owners:
| Version | Where | Meaning |
|---|---|---|
| Tool | VERSION, src/constants.py:1 | BuildHive release. setup.iss parses it (ISPP reads the first line), upgrade and the GUI compare it with the newest GitHub release tag, project.json buildhive_version records the tool that last wrote a project (an older tool refuses the project). Exported as BUILDHIVE_VERSION into hive-m containers for traceability. |
| Release | project.json release, e.g. ntl-v2026.1 | Template line the project is bound to: src/templates/<template>/<release>/. Same id as the yocto-manifests branch. Switch with configure project --release. |
| Firmware | project.json version, e.g. 2026.1.3 | Build within the release (<release number>.N). Exported as HIVE_VERSION; update-archive.bb / legacy-migration-update.bb in meta-aionyx-hive default UPDATE_VERSION / MIGRATION_VERSION from it (fallback BUILDHIVE_VERSION, then 0.0.0). Default SDK image tag. Set with configure project --version. |
A tool release therefore changes nothing in projects, firmware or SDK images unless template files changed (see Template update mechanism).
Adding a template release: cp -r src/templates/hive-m/ntl-v2026.1 src/templates/hive-m/ntl-v2026.2, set release and version in its project.json, update the branches. buildhive releases lists what a build ships; create defaults to the newest.
Release:
- Bump
VERSIONinsrc/constants.py. - Add a
## <x.y.z>section at the top ofCHANGELOG.md. Write it for users: what changed for them, not commit subjects. It is the GitHub release text and the GUIWhat's newdialog. - Commit, then tag and push:
git tag buildhive_v<x.y.z>,git push origin master buildhive_v<x.y.z>.
The tag starts .github/workflows/buildhive-release.yml:
| Job | Steps |
|---|---|
build (Windows, Linux x86_64 on Ubuntu 22.04, macOS arm64) | Tag must match VERSION. uv sync --locked, pytest, SBOM, PyInstaller. Windows: Inno Setup → BuildHive_<x.y.z>_Setup.exe. Linux/macOS: dist/buildhive/ as BuildHive_<x.y.z>_<platform>.tar.gz. |
release | tools/release_notes.py prints the CHANGELOG.md section (fails if missing), gh release create with all assets. |
Drafts and pre-releases are ignored by the update check. The asset name must match BuildHive_*_Setup.exe. Installers are release assets only, not committed. Local build without a release: make build, then compile setup.iss → dist/BuildHive_Setup.exe.
The installer (setup.iss) installs per user into %APPDATA%\NTL\BuildHive\bin, no admin. Same AppId on every version: Setup replaces the uninstall entry itself and deletes the old bin/ before copying, so an upgrade needs no separate uninstall. The upgrade command starts the downloaded installer two seconds after the CLI exits so bin/ is not in use. Uninstall removes the PATH entry and the app directory.
Documentation
docs/ is an mdBook. README.md is the front page: the workflow copies it to docs/README.md with docs/ stripped from its links (docs/README.md and docs/book/ are gitignored). Build locally:
sed 's#](docs/#](#g' README.md > docs/README.md
mdbook build docs # or: mdbook serve docs
.github/workflows/buildhive-docs.yml builds on every push to master touching buildhive/docs/** or buildhive/README.md and deploys to GitHub Pages (repository setting Pages > Source: GitHub Actions). New pages go into docs/SUMMARY.md.
GUI screenshots: python tools/gui_screenshots.py on a desktop session, no Docker needed. Rerun after visible GUI changes.
Logo: edit assets/logo.svg / assets/logo-wordmark.svg, then python tools/make_icons.py (regenerates app.ico, logo.png, docs/images/logo*.svg, docs/theme/favicon.*).
Template update mechanism
State per project: .buildhive_manifest.json (SHA-256 of every template file at last sync) and .buildhive_baseline/ (pristine text-file copies).
Every command (and the GUI on open) compares the shipped template files of the project's release with the manifest (common.template_outdated). Any file with a different hash, or missing from the manifest, means "update available" and the user is prompted; a tool release without template changes prompts nothing, buildhive_version is just restamped. A project written by a newer tool is refused. Per file, three hashes decide (old manifest, new template, current disk):
| Situation | Action |
|---|---|
| Template unchanged, user changed | keep user file |
| Template changed, user unchanged | overwrite (backup .bak) |
| Both changed | 3-way merge via git merge-file against the baseline; conflicts get git-style markers |
| Unmergeable (binary / no baseline) | prompt: keep yours / take template |
| File removed from template | kept on disk, reported |
| New template file | copied in |
images/ and project.json are never touched. Unresolved conflicts keep their old manifest hash, so they are re-prompted on the next update. buildhive_version is bumped only after all conflicts are resolved - an aborted update prompts again.
If the project is newer than the tool, no files are modified; the tool asks you to upgrade BuildHive.
Template edits during development: hive-m copies sw/meta-ntl-hive into the Yocto build tree on every container start, so layer changes in a project take effect on the next build without any sync step. Changes to src/templates/ reach existing projects only through the update flow, which the changed hashes trigger on the next command.