Skip to content

Configure the Development Environment

This guide covers tuning the devcontainer build environment for long builds and shared caches.

Prerequisites

Keep a Build Running Across VS Code Sessions

Closing the VS Code window stops a build running in its terminal (Keyboard Interrupt, closing down...). Run long builds in tmux, which the devcontainer provides; the session survives until the container is rebuilt.

Use the Shared State Mirrors

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.

Use Host Cache Directories

A shared DL_DIR or SSTATE_DIR outside the devcontainer (for example a network share or central build server) is bind-mounted into the container and used by kas directly.

First, 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).

Then enable DL_DIR and SSTATE_DIR in kas. Edit kas/common.yml and uncomment both, 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.

Serve a Local sstate Cache Over HTTP (Optional)

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

./.devcontainer/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

Tune Build Parallelism

The common-minimal block of kas/base.yml already sets the parallelism with weak assignments: BB_NUMBER_THREADS to the CPU core count, BB_NUMBER_PARSE_THREADS to half of it, and PARALLEL_MAKE to the core count times 1.25. Override them in a local_conf_header block of your kas target configuration:

local_conf_header:
  build-tasks: |-
    BB_NUMBER_THREADS = "8"
    PARALLEL_MAKE = "-j 10"
Variable Default Effect
BB_NUMBER_THREADS CPU core count Parallel BitBake tasks
PARALLEL_MAKE CPU cores × 1.25 Compilation parallelism

An SSD or NVMe drive for the build directory and at least 16 GB of RAM allocated to Docker keep long builds fast.

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 /workspaces/yocto/downloads/*      # clear downloads (forces re-fetch)
rm -rf /workspaces/yocto/sstate-cache/*   # clear sstate (slows next build)

Cache corruption

rm -rf /workspaces/yocto/sstate-cache/*
rm -rf /workspaces/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"

See also