Project configuration

Files in the project root

FilePurpose
project.jsonProject configuration (schema below). Never touched by template updates.
.buildhive_manifest.jsonSHA-256 per template file; drives change detection on template updates.
.buildhive_baseline/Pristine copies of text template files; base for 3-way merges.

project.json is loaded from the current working directory only (no upward search). A directory counts as a project if project.json exists, parses as a JSON object and has a name key. Optional fields with value null are omitted on save (exclude_none).

Common fields (both templates)

FieldTypeDefaultMeaning
idstringgeneratedUUID hex, set on first load. Names the per-project Docker volumes/containers.
namestring-Project name. Letters, digits, -, _; max 128 chars.
templatestring-hive-s or hive-m. Selects model and command set.
buildhive_versionstringtool versionVersion of the tool that last wrote the project. A mismatch with the running tool triggers the update flow (see development.md).

Git object used below: { "url": string, "branch": string }.

Hive-S schema

{
    "name": "...",
    "template": "hive-s",
    "sw": {
        "buildroot": { "url": "...", "branch": "..." },
        "uwm":       { "url": "...", "branch": "..." }
    },
    "hw": {
        "args": "--cpu-count=1 --with-rvc",
        "debug_args": "--ntl-debug --with-privileged-debug --hardware-breakpoints 4"
    },
    "flash": {
        "opensbi.bin": { "src": "0x...", "dst": "0x..." }
    }
}
FieldMeaning
sw.buildrootBuildroot repo, cloned in the SW container, built with ntl_defconfig.
sw.uwmUWM repo (private, SSH). Built before Buildroot; loader copied into the rootfs overlay.
hw.argsArguments for the LiteX SoC generator (make.py).
hw.debug_argsAppended to args with build hw --debug.
flashMap of image filename → {src, dst} hex address strings (parsed base-0). src = flash offset, dst = RAM load address (optional; e.g. uwm.xz has none). Consumed by build flash / info flash. Empty map is fatal at build.

Hive-M schema

{
    "name": "...",
    "template": "hive-m",
    "secrets": {
        "url": "https://secrets.ntl.dev",
        "role": "dev"
    },
    "sw": {
        "yocto_manifests": { "url": "...", "branch": "..." },
        "clone": {
            "uwm":     { "url": "...", "branch": "master" },
            "udm":     { "url": "...", "branch": "master" },
            "drivers": { "url": "...", "branch": "master" }
        },
        "buildsign": {
            "url": "https://sign.ntl.dev/api",
            "public_key": "<base64 Ed25519 key>"
        },
        "secure_boot": false,
        "sstate_mirror": {
            "url": "https://sstate.ntl.dev",
            "hashserv": "wss://hashserv.ntl.dev"
        }
    }
}
FieldType/DefaultMeaning
secretsoptionalOpenBao server holding build secrets. url: API base. role: OIDC auth role (default dev). mount: KV v2 mount (default buildhive). Secrets read: <mount>/mirror key SSTATE_MIRROR_AUTH, <mount>/users/<login email>/<sw.buildsign.secret> then <mount>/<sw.buildsign.secret>, key BUILDSIGN_TOKEN. Lookup order per secret: env var of the same name, BAO_TOKEN env (CI), cached OIDC token, browser login (buildhive login). Server errors degrade: warning and mirror off, signing fatal. Without a secrets block only the env vars are used.
sw.yocto_manifestsGitrepo init -u <url> -b <branch> on first container run.
sw.clonedict of Git, optionalExtra repos, cloned/pulled in parallel into sources/<name> and mounted at /custom_sources/<name>. Yocto recipes fetch uwm/udm from there (SRCREV=${AUTOREV}). --no-update skips the pull.
sw.buildsignoptionalSigning server for update archives. url: API base. public_key: pinned base64 Ed25519 key (32 bytes) used to verify signatures locally; if unset, verification is skipped with a warning. secret: KV path under the secrets mount holding key BUILDSIGN_TOKEN (default buildsign). Lookup: users/<login email>/<secret> (personal token) first, then <secret> (shared). Without a buildsign block, build update requires --no-sign.
sw.secure_bootbool, falsetrue: requires keys/psk.pem (fatal otherwise), adds require .../secure-boot.conf to local.conf, switches the update archive to signed-FIT components. false: strips the require line. See secure-boot.md.
sw.sstate_mirroroptionalShared sstate/download mirror (see sstate-mirror/README.md). url: HTTPS base serving sstate-cache/ and downloads/; written to local.conf as SSTATE_MIRRORS, SOURCE_MIRROR_URL, INHERIT += "own-mirrors" between # >>> / # <<< buildhive sstate mirror markers on every run. hashserv: optional BB_HASHSERVE address (wss://host through the mirror proxy or host:8687 plain), sets BB_SIGNATURE_HANDLER = "OEEquivHash". Credentials user:password (basic auth) from SSTATE_MIRROR_AUTH env or the secrets server (secrets field); written to ~/.netrc inside the container, never to local.conf. Unavailable: warning, marker block removed, build uses the local cache only.

Constants

ConstantValueUse
VERSIONsrc/constants.py:1Single source of the tool version. Tags Docker images, stamps project.json, update archives, the installer.
CONTAINER_USER / UIDntl / 1000In-container user.
WORK_DIR/workYocto work tree, backed by ntl_buildhive_sw_<id>.
SSTATE_DIR/mnt/ntl_sstateShared sstate/download cache, backed by ntl_buildhive_sstate.