mirror of
https://github.com/openglow-org/forgefirm.git
synced 2026-09-28 01:01:12 -07:00
ScottW514
dd6f459d7b
kas/README.md keeps the build, lockfile, pin and release procedure and a
short build-time facts list; its push/release checklist and Scarthgap
migration backlog are archived verbatim in CAMPAIGN-LOG ("Superseded
status notes"). The real-time argument (PREEMPT, why PREEMPT_RT is not
selectable or needed) joins the BRINGUP hardware facts bank next to the
ring measurements it rests on; the camera pointers go to the 0011-0013
patch headers; the image recipe's gfui-client comment drops its README
pointer.
Docs and a recipe comment only; no catalog consequence.
149 lines
6.7 KiB
Markdown
149 lines
6.7 KiB
Markdown
# Building ForgeFIRM with kas
|
|
|
|
The **forgefirm** repo is the base of the project: it controls the build,
|
|
the resulting firmware images land here, and all build/install docs live here.
|
|
It uses [**kas**](https://kas.readthedocs.io/) to manage Yocto layers and drive
|
|
the build.
|
|
|
|
## Baseline
|
|
|
|
| | |
|
|
|---|---|
|
|
| Yocto release | **Scarthgap 5.0 LTS** |
|
|
| Kernel | **linux-fslc 6.12** (mainline LTS, from meta-freescale) |
|
|
| Machine | `glowforge` (i.MX6 Solo SOM; Basic/Plus/Pro) |
|
|
| Distro | `forgefirm` |
|
|
| Image | `forgefirm-image` |
|
|
|
|
## Layout
|
|
|
|
```
|
|
openglow-forgefirm/
|
|
├── forgefirm/ ← THIS repo, the base
|
|
│ ├── kas/
|
|
│ │ ├── forgefirm-glowforge.yml ← build entry point
|
|
│ │ └── README.md ← this file
|
|
│ ├── meta-forgefirm/ ← the forgefirm layer (this repo)
|
|
│ ├── BUILD.md / INSTALL.md / SERIAL.md
|
|
│ ├── layers/ ← kas-cloned upstreams (gitignored)
|
|
│ ├── build/ ← bitbake output incl. images (gitignored)
|
|
│ ├── downloads/ sstate-cache/ ← caches (gitignored)
|
|
│ └── .gitignore
|
|
└── meta-openglow/ ← Glowforge BSP layers (local sibling checkout)
|
|
```
|
|
|
|
`meta-openglow` is referenced as a **local sibling** (`../meta-openglow`), so
|
|
its in-place edits are what gets built. The commented pinned-remote block in
|
|
`forgefirm-glowforge.yml` makes the forgefirm repo fully self-contained when
|
|
flipped on. The source repos the recipes build (`kernel-module-glowforge`,
|
|
`grblHAL-glowforge`, `forgectrl`, `python3-gfhardware`, `Glowforge-Utilities`)
|
|
are fetched by pinned `SRCREV` and are not needed as local checkouts.
|
|
|
|
## Prerequisites
|
|
|
|
A Linux build host, or **WSL2** on Windows (officially supported by Yocto).
|
|
|
|
> **WSL2 note:** keep this whole tree on the WSL2 *native* ext4 filesystem
|
|
> (e.g. `~/dev/openglow-forgefirm`), **not** under `/mnt/c/...`. The Windows
|
|
> mount breaks case-sensitivity/permissions and is very slow for Yocto. Give the
|
|
> WSL2 VM plenty of RAM and disk in `.wslconfig`.
|
|
|
|
```bash
|
|
pipx install kas # or: pip install kas
|
|
```
|
|
|
|
## Build
|
|
|
|
Run from the **forgefirm repo root** so outputs land inside it:
|
|
|
|
```bash
|
|
cd forgefirm
|
|
kas build kas/forgefirm-glowforge.yml # fetch layers + full build
|
|
kas shell kas/forgefirm-glowforge.yml # interactive bitbake environment
|
|
kas dump kas/forgefirm-glowforge.yml # print the resolved config
|
|
```
|
|
|
|
The bootable image lands in `build/tmp/deploy/images/glowforge/`. Flashing /
|
|
dual-boot install steps are in [`../INSTALL.md`](../INSTALL.md).
|
|
|
|
### Container build (optional, reproducible host)
|
|
|
|
```bash
|
|
cd forgefirm
|
|
kas-container build kas/forgefirm-glowforge.yml
|
|
```
|
|
|
|
## Pinning exact versions (reproducible builds)
|
|
|
|
The config tracks the `scarthgap` **branch** of each upstream layer. To lock
|
|
every layer to an exact commit:
|
|
|
|
```bash
|
|
kas lock kas/forgefirm-glowforge.yml # writes kas/forgefirm-glowforge.lock.yml
|
|
```
|
|
|
|
kas auto-loads the lockfile on subsequent runs. Commit it; refresh deliberately.
|
|
|
|
## Pins, pushes, and the release flow
|
|
|
|
The build is reproducible only when recipe pins, layer branches, and the kas
|
|
config move in the right order.
|
|
|
|
- **Every source repo is pinned.** `kernel-module-glowforge`,
|
|
`python3-gfhardware`, `Glowforge-Utilities`, `grblHAL-glowforge` and
|
|
`forgectrl` are fetched from GitHub at an exact `SRCREV`; there is no
|
|
`AUTOREV` anywhere. When a source repo changes: push it, then bump the pin
|
|
deliberately (BSP recipes in `meta-openglow`, ForgeFIRM components in
|
|
`meta-forgefirm`) and re-verify with `bitbake -c fetch <recipe>`. A
|
|
component's `SRCREV` (and the `PV` that moves with it) lives in
|
|
`<recipe>-pin.inc` next to the recipe, and nothing else goes in that file:
|
|
the image manifest leaves `*-pin.inc` out of the layer content hash, so a pin
|
|
bump changes the component's fingerprint and only that
|
|
(`docs/ACCEPTANCE.md`). A pin written into the recipe body still builds, but
|
|
counts as a platform change and forces a full acceptance campaign.
|
|
- **`meta-openglow` lives on its `scarthgap` branch** (Yocto layer convention;
|
|
the Dunfell-era `master` is untouched). Development happens on the local
|
|
sibling checkout; `scarthgap` is pushed as work lands.
|
|
- **The upstream layers are locked** by `kas lock` (poky, meta-openembedded,
|
|
meta-freescale, meta-freescale-distro); the lockfile is committed and
|
|
refreshed deliberately.
|
|
- **At release time**: flip `meta-openglow` in `forgefirm-glowforge.yml` from
|
|
the local-sibling block to the pinned-remote block (the commented block in
|
|
the file), refresh `kas lock`, tag all repos, and prove self-containment by
|
|
building from a fresh clone. Then `scripts/release.sh <version>` gates
|
|
(version single-source, rootfs-vs-slot size, installer-embedded pubkey vs the
|
|
signing key, factory-era fwup verification, and the acceptance gate: the
|
|
committed `releases/v<version>/acceptance.json` from the bench campaign must
|
|
authorize the built rootfs, `docs/ACCEPTANCE.md`), builds, packs and signs
|
|
`forgefirm.fw`, stages the assets with `sha256sums.txt`, and prints the
|
|
`gh release create` command. Assets and their exact names (the installer and
|
|
the update manager download them verbatim): `forgefirm.fw`,
|
|
`sha256sums.txt`, `forgefirm-image-glowforge.rootfs.wic.gz`, plus
|
|
`acceptance.json` and `acceptance.md`. The release tag `v<version>` =
|
|
`FORGEFIRM_RELEASE` = the rootfs `/etc/forgefirm-version` = the `.fw`
|
|
meta-version; `release.sh` enforces the agreement.
|
|
|
|
For fast iteration on a source repo, bump its pin per iteration, or add a
|
|
**local, untracked** `externalsrc` bbappend pointing at a working checkout;
|
|
never commit one, or released images stop matching the pins.
|
|
|
|
## Build-time facts
|
|
|
|
- `ACCEPT_FSL_EULA = "1"` is set in the kas config: the image carries NXP's
|
|
VPU firmware blob, and `firmware-imx-lic` ships the EULA text beside it.
|
|
- Every `LICENSE` string in the layers (`meta-forgefirm`, `meta-glowforge-bsp`,
|
|
`meta-openglow-core`) is SPDX; recipes for third-party components with more
|
|
than one license (`wlconf`, `python3-gfhardware`) declare each with a
|
|
checksum on its license text.
|
|
- `forgefirm-image-dev` is a strict superset of `forgefirm-image` (the bench
|
|
image, `docs/ACCEPTANCE.md`); every build produces both.
|
|
- The kernel is `linux-fslc` with the board's device tree, config fragment and
|
|
layer patches in `meta-openglow/meta-glowforge-bsp/recipes-kernel/linux/`;
|
|
the bbappend header lists the patches and `glowforge.cfg` documents the
|
|
config. The bootloader recipe is `u-boot_2020.01.bb` in `recipes-bsp`.
|
|
|
|
Design facts (the pulse ring, real-time choices, hardware measurements) are in
|
|
`docs/BRINGUP.md` ("Hardware facts bank") and
|
|
`kernel-module-glowforge/UAPI.md`; bench status and open work are
|
|
`docs/BRINGUP.md`; the dated record is `docs/CAMPAIGN-LOG.md`.
|