deedone/highheat

1. What this repo is

HighHeat is a command-line tool that sits on top of an existing Yocto or Moulin workspace and accelerates the inner development loop. It does not replace BitBake; instead, it finds the already-built project, runs the relevant compile/install/deploy steps directly in the workdir, and pushes the result to a target.

2. Top-level orchestration

The entry point is src/highheat/main.py, which likely parses the hh CLI and dispatches commands such as edit, build, deploy, build-deploy, info, and editimg. This is the central controller that ties together project discovery, image handling, transport, and command execution.

3. Project discovery and abstraction layer

The project.py family is the core domain model for “what project am I working on?” It appears to encapsulate Yocto/Moulin project metadata, work directories, source directories, deploy artifacts, and recipe mapping. The variants:

- project_linux.py for Linux/kernel-specific handling

- project_xen.py for Xen-related handling

- project_interactive.py for interactive image editing workflows

suggest that the system adapts its behavior based on project type rather than using one generic build path.

4. Yocto integration

yocto.py and bbdata.py are the repository’s bridge into BitBake-generated state. HighHeat likely reads existing metadata and filesystem layout from the Yocto build tree, rather than invoking BitBake for dependency resolution. This is the boundary that makes the tool fast: it depends on prior BitBake output but avoids BitBake during iterative edits.

5. Build and shell execution

shell.py and moulin_helpers.py are the execution layer for local shell commands and environment-specific command generation. The README’s confirmation and dry-run behavior implies this layer centralizes command construction, prompting, and execution. This is the main trust boundary: HighHeat shells out to build, install, deploy, mount, unpack, and repack commands on the host.

6. Target transport

transport.py and transport_rsync.py represent the delivery path from workstation to target. The repo supports both local and remote targets, and the dedicated rsync transport suggests file synchronization is a first-class mechanism for deployment. This layer isolates “how bytes get to the target” from the project and image logic.

7. Image handling subsystem

image.py is the abstraction over target image formats, with format-specific implementations in:

- image_ext4.py

- image_ramfs_gz.py

- image_uimage.py

- image_dtb.py

This is a major architectural boundary: HighHeat treats “deploy target” as either a directory or a packaged image, and selects unpack/edit/repack behavior based on the image type.

8. Interactive image editing

project_interactive.py and the editimg command support a higher-touch workflow: download an image, unpack or mount it, allow manual edits, then write it back. The README shows this for initramfs and DTB files, so the workflow includes both filesystem-style images and single binary artifacts. DTB handling is especially specialized because decompilation/recompilation is used to preserve editable structure.

9. Configuration and runtime behavior

config.py and log.py handle user preferences and diagnostics. The config file controls editor choice, interactive editor behavior, confirmation prompts, download cache location, cleanup interval, and gzip compression level. Logging and verbosity are runtime concerns that influence nearly every subsystem but do not change the core architecture.

10. External environment and assumptions

HighHeat is built around a pre-existing Yocto or Moulin workspace and assumes the project has already been built at least once with BitBake. It is designed to run from inside the workspace root so it can autodetect the current project and domain. That means the architecture depends heavily on filesystem layout and BitBake output conventions, not on a long-running service or database.

11. Main data flows

The most important flow is:

source/workdir discovery -> local build action -> artifact selection -> transport -> target update.

A second major flow is:

remote/local image acquisition -> unpack/mount/decompile -> interactive edit -> repack -> redeploy.

These flows show that HighHeat is primarily a file- and shell-orchestration tool, with no persistent backend.

12. Key boundaries to draw in an architecture diagram

The diagram should clearly separate:

- the CLI/controller layer

- project/Yocto metadata resolution

- build and shell execution on the host

- image-format-specific unpack/edit/repack logic

- transport to local or remote targets

- the target filesystem/image itself

The important architectural point is that HighHeat does not own the build system or the target image lifecycle; it orchestrates around them.