Development

Repo layout

PathContent
src/main.pyEntry point; signal handlers stop running containers on Ctrl-C.
src/commands/__init__.pyCommand 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__.pyInit script prepended to every hive-m container run.
src/project.pyProject load/save/create, Docker image build, container/volume orchestration.
src/state.pyDocker client plus the running container/process handles the Ctrl-C handler stops.
src/common.pyTemplate 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.pyArgument validation: project names, module names, file paths.
src/log.pyConsole output with the INFO:/WARNING:/ERROR:/OK: prefixes the GUI colors by.
src/vault.pySecrets server client: OIDC login, token cache, secret lookup.
src/signing.pyBuildsign client. Purposes update and license, each with its own message prefix.
src/uwm_app.pyApp repos: SDK container build, bundle and update package, license payload and check.
src/selfupdate.pyRelease lookup on GitHub, installer download and start (upgrade, GUI update button).
src/constants.pyVERSION, container constants, SECRETS_URL, SDK_IMAGE.
src/changelog.py, CHANGELOG.mdRelease 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.pyIMAGE_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.pyBitBake 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.pyRenders docs/images/gui/*.png for the GUI docs.
tools/make_icons.pyRenders assets/app.ico, assets/logo.png and the docs logo copies from assets/logo.svg.
tools/make_sbom.pyWrites assets/sbom.json (CycloneDX 1.5) from the runtime packages installed in the venv. Runs in make build.
tools/release_notes.pyPrints 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-versionDependencies (runtime in [project], tools in the dev group), lockfile, interpreter version for uv.
buildhive.specPyInstaller spec, one analysis, two exes (buildhive.exe, buildhive-gui.exe).
setup.issInno 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:

VersionWhereMeaning
ToolVERSION, src/constants.py:1BuildHive 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.
Releaseproject.json release, e.g. ntl-v2026.1Template line the project is bound to: src/templates/<template>/<release>/. Same id as the yocto-manifests branch. Switch with configure project --release.
Firmwareproject.json version, e.g. 2026.1.3Build 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:

  1. Bump VERSION in src/constants.py.
  2. Add a ## <x.y.z> section at the top of CHANGELOG.md. Write it for users: what changed for them, not commit subjects. It is the GitHub release text and the GUI What's new dialog.
  3. 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:

JobSteps
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.
releasetools/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):

SituationAction
Template unchanged, user changedkeep user file
Template changed, user unchangedoverwrite (backup .bak)
Both changed3-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 templatekept on disk, reported
New template filecopied 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.