GUI
PySide6 desktop front end for the CLI. Same features as the command line except the interactive targets (configure linux|uboot|buildroot, shell, code), plus recipe search and in-place project updates.
Starting
| How | Notes |
|---|---|
Start menu BuildHive | Runs buildhive-gui.exe, no console window. Installed by BuildHive_Setup.exe. |
buildhive gui | From any terminal. |
buildhive.exe without arguments | Same as buildhive gui, keeps the console window. |
python src/main.py | Development checkout, commands run through main.py instead of buildhive.exe. |
The most recently opened project opens at start. Docker Desktop is needed for builds, indexing and create, not for opening the GUI, editing packages or updating a project.
Window

| Area | Content |
|---|---|
| Sidebar | Pages: Project, Configure, Build & Deploy, Settings, About at the bottom. Tool version under the name. Update to x.y.z appears when a newer release exists, see BuildHive updates. |
| Header | Project name, template tag, release and firmware version tag (ntl-v2026.1 ยท 2026.1.0), path. Show folder opens the project directory in the file manager. Right: Docker daemon state, checked at start and every 10 s. Docker not running means every command that needs Docker fails until Docker Desktop is up; the GUI keeps working. |
| Page | Cards per topic. Each card names what it does under its title. |
| Output | Log of the running command, see below. The splitter above it is draggable; pages scroll, so the console can take most of the window. |
Output panel
Every button that runs a command spawns buildhive <command> in the project directory and streams its output line by line into the panel. The line $ buildhive ... marks the start.
| Element | Behavior |
|---|---|
| Header text | Command and elapsed time while running, then Done (m:ss) or Failed, exit N. During a bitbake run also the first running task (linux-xlnx do_compile 45%) and how many more run. |
| Progress bar | Bitbake tasks done / total, tooltip lists every running task. Fed by the buildhive bitbake UI (src/scripts/bitbake_ui.py, installed into the checkout by the init script and selected with BITBAKE_UI=buildhive; it prints knotty's log plus @@BH {json} state lines the GUI parses) and, as fallback, knotty's Running task N of M (...) lines. Hidden when the command is done. |
| Search | Ctrl+F focuses the field. All matches are highlighted with a count; Enter / F3 jumps to the next, Shift+Enter / Shift+F3 to the previous, wrapping at the ends. Jumping pauses Follow. |
| Follow | Checked: the newest line stays in view. Scrolling up unchecks it, scrolling back to the end checks it again. |
| Clear | Empties the log. |
| Stop | Terminates the command and runs docker stop on the project's containers. Enabled only while a command runs. |
| Colors | $ orange, ERROR: red, WARNING: yellow, OK: green, INFO: blue, rest grey. ANSI codes are stripped. |
One command at a time. While one runs, the Project, Configure and Build & Deploy pages are disabled; Settings stays usable. Closing the window stops a running command first.

Project
| Item | Action |
|---|---|
| Open folder | Directory picker. The directory needs a project.json, or a buildhive-app.json for a uwm app repo. With neither, the GUI offers app init in that directory. Ctrl+O works on every page. |
| Recent | Last 10 opened projects, newest first. Double-click opens, right-click removes the entry. Missing directories are dropped. |
| New project | buildhive create -n <name> -t <template> -r <release> in the chosen parent directory, then opens the new project. Templates: hive-m, hive-s; the Release list shows the shipped template releases of the template, newest first. |
Project update
Opening a project whose template files (its release under src/templates/) changed since the last sync opens a dialog. A tool release without template changes opens nothing. Cancel keeps the project closed. Yes runs the template update in the GUI (no terminal), the same merge the CLI does on the next command in the project directory.

| Section | Meaning |
|---|---|
| Updated | Template file changed, yours did not. Overwritten, backup as .bak. |
| Added | New template file. |
| Merged | Both changed, 3-way merged against the stored baseline. Backup as .bak. |
| Merged with conflicts | Both changed the same lines. The file contains <<<<<<< markers. |
| Conflicts - skipped | Both changed, not mergeable (binary or no merge base). Per-file choice in the dialog: keep my version or take the template version. |
| Kept your version | You changed it, the template did not. |
| Removed | Dropped from the template, you had not changed it. |
| Removed from template | Dropped from the template but you changed it. Moved to .bak so the build no longer uses it. |
Finish update is enabled once no file contains merge markers. Resolve the markers in an editor, then Re-check. Finish writes the manifest, stamps the tool version into project.json and adds sections newer templates need. Cancel after a merge leaves the merged files in place, the manifest keeps the old hashes and the dialog appears again on the next open.
A project created by a newer BuildHive than the installed one is refused with a message to update BuildHive.
Configure
Release and version (both templates). Release: the template line the project is bound to, read-only here (configure project --release on the CLI). Version: firmware build x.y.z, Apply runs configure project --version <value> and reopens the project so the header tag follows.
hive-m

Boot bitstream and device tree. Inputs for Build SW image. The bitstream ends up in BOOT.bin and the SD image, so this is what a device boots from the card.
| Row | Command | Effect |
|---|---|---|
| XSA | configure xsa -f <file> | Extracts the .bit from the Vivado archive to sources/sdt/AionyxBaseTop.bit, header validated. |
| Bitstream | configure bitstream -f <file> | Copies a .bit to sources/sdt/AionyxBaseTop.bit. Same target as XSA, use one of the two. |
| Device tree | configure dts -f <file> | Copies the include to sw/meta-ntl-hive/recipes-bsp/device-tree/files/ntl-custom.dtsi, merged into the kernel device tree. |
Browse fills the field, Apply runs the command. For a device already in the field use the Update archive on Build & Deploy instead, which imports the bitstream at runtime.
Image packages. Edits IMAGE_INSTALL:append in sw/meta-ntl-hive/conf/layer.conf directly, no command. Applied on the next Build SW image. Same file as buildhive packages, see commands.md.
| Element | Behavior |
|---|---|
| Installed list | Current entries. Select one or more, Remove selected. |
| Add field | Package name, Add or Enter. Allowed: lowercase letters, digits, + . _ -. Several names separated by spaces. |
| Filters | All recipes / Packagegroups only, and All layers / one layer. With filters set and an empty field the list shows everything matching. |
| Suggestions | Filtered while typing. Ranking: exact name, recipes whose runtime dependencies contain the term (that is how gcc finds packagegroup-core-buildessential), name prefix, summary, substrings. Click fills the field, double-click adds. Hover shows the recipe description. |
| Build index / Rebuild index | Runs buildhive packages index in the build container and writes build/recipe-index.json. The hint line shows how many recipes are indexed and when. Rebuild after changing the Yocto manifest. |
The index lists recipes, not the split runtime packages a recipe produces (gcc is listed, gcc-symlinks is not). Host-only recipes (-native, -cross, nativesdk-, images) are excluded.
Kernel, U-Boot and Buildroot menuconfig are terminal-only: buildhive configure linux | uboot | buildroot.
hive-s

Bitstream: configure bitstream -f <file>, copied into the project and used by Build flash image.
app

Read-only summary of buildhive-app.json: SDK image, manifest, build command, bundle files, license fields. Edit buildhive-app.json opens the file in the default editor. Reload reads it again. Schema: apps.md.
Build & Deploy
Builds run with -v so the container output shows in the panel. Output files land in images/.
hive-m

Build
| Button | Command | Options |
|---|---|---|
| Build SW image | build sw -v | Rebuild adds --rebuild (clean the build volumes first). Skip repo pulls adds --no-update (no repo sync, no git pull of the cloned repositories). |
| Build kernel | build kernel -v | Kernel Image only. |
| Export SDK | export sw -v | Cross toolchain installer for application development, see hive-m.md. |
Update archive. Builds images/update.raucb from the last Build SW image for devices in the field, see updates.md.
| Element | Command / flag |
|---|---|
| Only these components | --include <list> with the checked components. Unchecked: default set (everything except fitimage). |
| Bitstream | --bitstream <file>, .bit or .bin. Imported by uwm on the device and installed as the boot bitstream. |
| DT overlay | --dtbo <file>, .dtso or .dtbo. Needs a bitstream. |
| Build update | build update -v with the flags above. |
| Skip signing | Adds --no-sign. |
| Sign existing | build update --sign-only -v, signs the archive already in images/. |
Signing needs the buildsign token from the secrets server or from Settings.
hive-s

| Button | Command | Options |
|---|---|---|
| Build HW | build hw -v | Vivado on PATH. RISC-V JTAG debug adds --debug. |
| Build SW | build sw -v | Buildroot. |
| Build flash image | build flash -v | Needs the bitstream from Configure and built software. |
| Deploy flash | deploy flash -v | Vivado on PATH, device connected. |
app

App package. Output in out/, see apps.md.
| Element | Command / flag |
|---|---|
| SDK version | --sdk <x.y.z>. Empty: sdk from the config. |
| App version | --version <v>. Empty: manifest version. |
| Build app | app build -v with the flags above. |
| Skip build | Adds --no-build. |
| Skip signing | Adds --no-sign. |
| Sign existing | app sign. |
License. Shown when the config has a license section. One input per license.fields entry. Empty inputs are not passed, so field defaults apply.
| Element | Command / flag |
|---|---|
| Create license | app license --edition <e> --<field> <value> ..., -o <file> when Output is set. |
| Verify | app license --verify <file>. |
Stop also stops the app build container (buildhive-app-<directory>).
Clean artifacts
buildhive clean after confirmation. Deletes the Docker build volumes, so the next build starts from scratch. Sources, images/ and the sstate cache stay (clean --all for the sstate cache is CLI-only).

Settings

| Card | Content |
|---|---|
| Secrets server | Login runs buildhive login: browser login with the company SSO, token cached next to the GUI settings. Logout deletes the token. Needs an open project because the server URL comes from project.json. |
| BuildHive updates | Check for updates queries the GitHub releases now, logging in to the secrets server first if needed. Result goes to the output panel. |
| Credentials | Overrides for BUILDSIGN_TOKEN (signing) and SSTATE_MIRROR_AUTH (user:password). Passed to every command the GUI runs. Empty fields mean the command fetches them from the secrets server. Show toggles masking, Save writes both. |
About

| Card | Content |
|---|---|
| Header | Version, links to website, source, documentation and releases. |
| Environment | Python and Qt versions, install directory, GUI settings file, build container image. |
| License | Copyright and the LGPL notice for Qt/PySide6. |
| Software bill of materials | Every Python package in the installer with version and license, read from assets/sbom.json (CycloneDX 1.5, written by tools/make_sbom.py during make build). Double-click opens the project page. |
BuildHive updates
Releases: NetTimeLogic/Tools, tags buildhive_v<x.y.z>, asset BuildHive_<x.y.z>_Setup.exe. The repo is private, so the GUI reads a GitHub token with Contents: read from the secrets server (buildhive/github, key GITHUB_TOKEN; GITHUB_TOKEN in the environment overrides it).
| Step | Behavior |
|---|---|
| Start, then every 3 h | Silent check with the cached secrets login. No login, offline or API error: nothing happens. Skipped while an update downloads. |
| Newer release | INFO: BuildHive x.y.z is available in the output, Update to x.y.z in the sidebar. |
| Update button | Confirmation, then the installer downloads to the temp dir and starts. BuildHive closes; the installer removes the old version and installs the new one (per user, no admin). Refused while a command runs. On Linux/macOS the button opens the releases page. |
| Errors | ERROR: Update failed: ... in the output, the button stays. |
| First start of a new version | What's new dialog with the CHANGELOG.md sections after the version of the last GUI start. Nothing on a fresh install or on a downgrade. |
Same from a terminal: buildhive upgrade (commands.md).
Settings file: gui.json in the OS config dir, %LOCALAPPDATA%\buildhive\ on Windows, ~/.config/buildhive/ on Linux. Plain text: the credential overrides, the recent project list and last_version (version of the last GUI start, for the What's new dialog).
Troubleshooting
| Symptom | Cause / fix |
|---|---|
Docker not running in the header | Start Docker Desktop. The header updates within 10 s. |
Command fails at once with Docker is not running or accessible | Same, the command checked Docker itself. |
Failed, exit N | Read the log, the last ERROR: line names the cause. Rerun from a terminal with the same command for an interactive session. |
| Nothing happens on double-click of the Start menu entry | The windowed exe has no console to print to. Run buildhive.exe gui from a terminal to see the error. |
layer.conf not found - update the project first | The project predates the meta-ntl-hive layer. Reopen it to get the update dialog. |
| Suggestions stay empty | No index yet, click Build index. Needs Docker and the first build environment setup (repo sync), a few minutes. |
| Project update shows conflicts every time | Merge markers still in a file. Resolve them, Re-check, Finish update. |
Implementation
| File | Content |
|---|---|
src/gui/app.py | QApplication, Fusion style, dark palette, stylesheet. |
src/gui/main_window.py | Sidebar (page list, About pinned at the bottom), header, page stack, output panel, run_cli(), Docker check, project open and update flow. |
src/gui/pages.py | Project, Configure, Build & Deploy and Settings pages. card() = titled section, ActionRow = button, description, options, FileRow = path field with Browse. |
src/gui/runner.py | CommandRunner thread: Popen of buildhive.exe (buildhive on Linux/macOS) next to the GUI exe (or main.py in a checkout), CREATE_NO_WINDOW, credentials via environment. DockerCheck thread. |
src/gui/update.py | Project update dialog, calls Project.update() and finish_update() in-process. |
src/gui/app_update.py | UpdateCheck and UpdateInstall threads around src/selfupdate.py, see BuildHive updates. |
src/gui/settings.py | gui.json load/save. |
src/gui/whats_new.py | What's new dialog, text from src/changelog.py. |
src/gui/about.py | About page, renders assets/sbom.json. |
src/gui/assets.py | Path to assets/ (checkout or PyInstaller bundle), logo pixmap. |
src/gui/style.py | Qt stylesheet, accent #ffaa28. |
tools/gui_screenshots.py | Renders the screenshots on this page into docs/images/gui/. |
buildhive.spec produces two exes from one analysis: buildhive.exe (console) and buildhive-gui.exe (console=False). Both run main.py; without arguments it starts the GUI, which spawns the console exe for commands. The windowed exe has no stdout or stderr, so nothing on the GUI path may exit on a failed print or on a missing Docker daemon: state.connect() runs only on the CLI path, stop_container() is a no-op without a connection.