Configure the Development Environment¶

For first-time devcontainer setup, see the First Build tutorial.

Sstate Cache Mirror¶

Yocto uses a shared state (sstate) cache to speed up incremental builds by reusing previously built components.

By default, kas/common.yml configures two remote SSTATE_MIRRORS that BitBake queries before rebuilding any task:

SSTATE_MIRRORS ?= "file://.* https://reed-cache01.tolomeo.io/sstate-cache/PATH;downloads=PATH \
                   file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH \
                   "

• reed-cache01.tolomeo.io — project-specific mirror with ToloMEO build artifacts
• sstate.yoctoproject.org — public Yocto mirror as a fallback

No local setup is required. BitBake resolves cache hits automatically over HTTPS. To override the mirrors, edit SSTATE_MIRRORS in kas/common.yml.

Using External Cache Directories¶

If you have a shared DL_DIR or SSTATE_DIR available outside the devcontainer (e.g., a network share or central build server), bind-mount those paths into the container and configure kas to use them directly.

Step 1: Add bind mounts to the devcontainer¶

Edit .devcontainer/devcontainer.json and add mount entries, replacing source paths with the actual host-side paths:

"mounts": [
  {
    "source": "/path/on/host/yocto-downloads",
    "target": "/workspaces/yocto/downloads",
    "type": "bind"
  },
  {
    "source": "/path/on/host/yocto-sstate-cache",
    "target": "/workspaces/yocto/sstate-cache",
    "type": "bind"
  }
]

Rebuild the devcontainer after saving (Dev Containers: Rebuild Container).

Step 2: Enable DL_DIR and SSTATE_DIR in kas¶

Edit kas/common.yml and uncomment DL_DIR and SSTATE_DIR, matching the target paths above:

DL_DIR ?= "/workspaces/yocto/downloads"
SSTATE_DIR ?= "/workspaces/yocto/sstate-cache"

DL_DIR and SSTATE_DIR take precedence over SSTATE_MIRRORS for locally present artifacts. Leaving SSTATE_MIRRORS active as a fallback is safe.

Local HTTP sstate server (optional)¶

To expose a locally mounted sstate directory as an HTTP mirror:

./scripts/start-sstate-server.sh    # start on port 8000
tail -f /tmp/sstate-server.log      # view logs
kill $(cat /tmp/sstate-server.pid)  # stop

Then add to SSTATE_MIRRORS in kas/common.yml:

SSTATE_MIRRORS ?= "file://.* http://localhost:8000/sstate-cache/PATH;downloadfilename=PATH"

If port 8000 is in use: sudo lsof -ti:8000 | xargs kill -9

Performance Optimization¶

Add the following to your kas target configuration:

local_conf_header:
  build-tasks: |-
    BB_NUMBER_THREADS ?= "${@oe.utils.cpu_count()}"
    BB_NUMBER_PARSE_THREADS ?= "${@max(1, oe.utils.cpu_count() // 2)}"
    PARALLEL_MAKE ?= "-j ${@int(oe.utils.cpu_count() * 1.25)}"
    PARALLEL_MAKEINST ?= "${PARALLEL_MAKE}"

Use SSD/NVMe storage for the build directory. Allocate at least 16 GB RAM to Docker.

Troubleshooting¶

Container won't start¶

Ensure Docker is running and has sufficient resources. Check available disk space (50 GB minimum). Restart Docker: sudo systemctl restart docker.

Slow builds¶

Verify mirror reachability:

curl -I https://reed-cache01.tolomeo.io/sstate-cache/
curl -I http://sstate.yoctoproject.org/all/

If using external cache directories, verify bind mounts are active:

ls /workspaces/yocto/downloads
ls /workspaces/yocto/sstate-cache

Out of disk space¶

df -h
rm -rf build/tmp-*              # clean build temporaries
rm -rf yocto-downloads/*        # clear downloads (forces re-fetch)
rm -rf yocto-sstate/*           # clear sstate (slows next build)

Cache corruption¶

rm -rf yocto-sstate/*
rm -rf yocto-downloads/*        # only if checksums are wrong

BitBake fails with Errno 1 Operation not permitted (Ubuntu 24.04 host)¶

Ubuntu 24.04 restricts unprivileged user namespaces by default. Because the devcontainer shares the host kernel, BitBake cannot create the namespaces it needs. This is a known Yocto issue.

Apply one of the following on the host machine:

Temporary (lost on reboot):

echo 0 | sudo tee /proc/sys/kernel/apparmor_restrict_unprivileged_userns

Persistent:

Create /etc/sysctl.d/60-apparmor-namespace.conf:

kernel.apparmor_restrict_unprivileged_userns=0

Reboot after creating the file.

System becomes unresponsive during builds¶

Reduce parallelization:

export BB_NUMBER_THREADS="2"
export PARALLEL_MAKE="-j 4 -l 4"