yocto (Yocto Project / poky + kas)

What it is

The Yocto Project builds custom Linux distributions from recipes. poky is the reference distribution; kas is the config-driven wrapper that pins layers/revisions in one YAML file. This is how we build appliance images for embedded targets.

Requirements (read before building)

Disk: ~100 GB+ free (sstate cache + downloads grow fast; 200 GB is comfortable).
RAM: 16 GB (8 GB works with a big swapfile and patience).
Long builds: first core-image-minimal can take hours on a laptop.

Install (host tools)

sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential \
  chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils \
  iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
  pylint xterm python3-subunit mesa-common-dev zstd liblz4-tool file locales
pipx install kas

Recommended: build inside the crops/poky container

The laptop should not be a Yocto host. Use the official container (Ubuntu base, all deps preinstalled):

docker run --rm -it \
  -v ~/yocto:/work -w /work \
  crops/poky:ubuntu-22.04
# inside the container:
git clone -b scarthgap https://git.yoctoproject.org/poky
source poky/oe-init-build-env build
bitbake core-image-minimal

With kas instead of manual sourcing:

kas build project.yml        # runs bitbake per the pinned layer config
kas shell project.yml        # interactive shell inside the build env

A dedicated Proxmox CT/VM for Yocto builds (100+ GB disk, 16 GB RAM, Docker or bare Debian) may come later — designs should already assume builds run there, not on the laptop.

Authenticate

None. Layer repos clone over HTTPS/SSH (use Forgejo mirrors where they exist: code.portugalfuturista.org). Private-layer SSH keys stay in ~/.ssh; never in recipes.

Configure for this environment

Set DL_DIR and SSTATE_DIR outside the build tree so multiple builds share downloads/cache (local.conf):
```
DL_DIR ?= "/work/downloads"
SSTATE_DIR ?= "/work/sstate-cache"
```
Pin every layer branch in the kas YAML — reproducibility over freshness.
Archive release images to MinIO (http://192.168.0.40:9000).

Self-hosted equivalent

Yocto is inherently self-hosted — the entire toolchain and mirrorable source cache live on your infrastructure. For air-gapped reproducibility run an sstate mirror on MinIO (SSTATE_MIRRORS in local.conf).

Aurélio integration

The embedded-linux skill drives kas/bitbake for image builds. Images produced are flashed with tools from esptool.md / uboot-tools.md and target the mqtt-local connector at runtime.

Verify

kas --version
# kas 4.x
docker run --rm crops/poky:ubuntu-22.04 bitbake --version
# BitBake Build Tool Core version 2.x ...

Troubleshooting

do_fetch stalls — upstream git flaky; set a premirror or retry; check you cloned the matching release branch (e.g. scarthgap) for all layers.
Disk full mid-build — Yocto needs ~100 GB; clean with bitbake -c cleanall <recipe> or prune tmp/ (keep DL_DIR/SSTATE_DIR).
Host distro too new/old for a release — that's exactly why we build in crops/poky; pick the container Ubuntu version matching the Yocto release.
kas can't find layers — paths in the kas YAML are relative to the repo root; run kas build from there or pass absolute --target paths.

3.4 KiB Raw Permalink Blame History