Configure the Development Environment¶
This guide covers tuning the devcontainer build environment for long builds and shared caches.
Prerequisites¶
- A working devcontainer; see Build the ToloMEO Reference Image
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 artifactssstate.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 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:
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:
| 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:
If using external cache directories, verify bind mounts are active:
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):
Persistent:
Create /etc/sysctl.d/60-apparmor-namespace.conf:
Reboot after creating the file.
System becomes unresponsive during builds¶
Reduce parallelization:
See also
- Manage User Accounts — production image accounts and passwords
- kas Configuration — build paths, mirrors, and fragments
- Build the ToloMEO Reference Image — first build and boot