Speed Up Yocto Builds

Yocto can reuse two types of data from earlier builds:

Directory	Stored data	Benefit for later builds
DL_DIR	Downloaded source archives and repositories	BitBake reads the local copy instead of downloading it again.
SSTATE_DIR	Results from completed BitBake tasks	BitBake restores compatible results instead of rebuilding them.

The first build fills these caches, so it might not be noticeably faster. Later compatible builds benefit from the saved data.

Before You Start

You need a configured BSP workspace and enough free disk space for the build output and both caches.

Run every command in this guide from the root of the selected BSP workspace. This is the directory that contains the BSP's metadata layer, not the layer's kas directory.

Check the available space before starting:

Development host

df -h "$HOME"

Follow the selected board's image build guide for its current disk-space requirement.

1. Create the Shared Cache Directories

Create one download cache and one shared-state cache outside the BSP workspaces:

Development host

mkdir -p "$HOME/bitbake/downloads" "$HOME/bitbake/sstate-cache"

Keeping the caches outside a workspace allows multiple BSP workspaces to use the same directories while retaining their own separate build directories.

2. Build an Image with the Shared Caches

The goal is to make later builds faster by reusing source files that BitBake has already downloaded and results from tasks that BitBake has already completed. The first build downloads missing sources into DL_DIR and stores reusable task results in SSTATE_DIR.

The cache paths are the key part of this workflow. Every later build that should reuse this data must set DL_DIR and SSTATE_DIR to the same paths:

Shared cache paths

export DL_DIR="$HOME/bitbake/downloads"
export SSTATE_DIR="$HOME/bitbake/sstate-cache"

Both example builds below use these exact paths. If the second build points to different directories, it cannot reuse the data populated by the first build.

The following example starts with a Grinn Genio BSP build. For another platform, use the machine name and kas file from its image build guide.

Example: Grinn Genio BSP

Run from the Grinn Genio BSP workspace root:

Development host

DL_DIR="$HOME/bitbake/downloads" \
SSTATE_DIR="$HOME/bitbake/sstate-cache" \
KAS_MACHINE=grinn-genio-700-sbc \
KAS_CONTAINER_IMAGE_DISTRO=debian-bookworm \
kas-container build meta-grinn-genio/kas/default.yml

The variables have the following roles:

Variable	Purpose
DL_DIR	Selects the shared directory for downloaded source data.
SSTATE_DIR	Selects the shared directory for reusable task output.
KAS_MACHINE	Selects the board configuration.
KAS_CONTAINER_IMAGE_DISTRO	Selects the container distribution.

The kas file at the end of each command selects the BSP's base build configuration. Use the machine and kas file from the board's image build guide when building a different Grinn board or configuration.

Wait until this build finishes and returns to the shell prompt before starting another build.

3. Reuse the Caches in Another Platform Build

Now build another platform with the same DL_DIR and SSTATE_DIR. The example below uses Grinn Astra BSP after the Grinn Genio BSP build has finished.

Example: Grinn Astra BSP

Run from the Grinn Astra BSP workspace root:

Development host

DL_DIR="$HOME/bitbake/downloads" \
SSTATE_DIR="$HOME/bitbake/sstate-cache" \
KAS_MACHINE=grinn-astra-1680-sbc \
KAS_CONTAINER_IMAGE_DISTRO=debian-bookworm \
kas-container build meta-grinn-astra/kas/default.yml

Do not run the two example builds concurrently. Wait for the first build to finish, change to the second workspace, and then start the second build. The order is not important: you can build Grinn Astra BSP first and reuse its caches in a later Grinn Genio BSP build.

Keep both DL_DIR and SSTATE_DIR unchanged; pointing a build at different paths creates or uses different caches.

BitBake then:

• reads already downloaded source data from DL_DIR;
• restores compatible task output from SSTATE_DIR;
• rebuilds tasks whose inputs or configuration have changed.

You do not need to copy cache files into the workspace. kas-container mounts the directories selected by DL_DIR and SSTATE_DIR into the build container.

4. Confirm Cache Reuse

Look for an Sstate summary near the start of the second build. A previously observed build using the shared cache reported:

Example output

Sstate summary: Wanted 3268 Local 189 Mirrors 0 Missed 3079 Current 1998 (5% match, 41% complete)

This recorded result means:

• Local 189: 189 tasks were restored from the local SSTATE_DIR and did not run again. A nonzero Local value confirms shared-cache reuse.
• Current 1998: 1,998 tasks were already current in that workspace's build directory and did not run again.
• Together, the build avoided running 2,187 tasks: 189 restored from shared state plus 1,998 already current.
• Missed 3079: 3,079 shared-state lookups did not find a compatible result, so those tasks needed to run.

The 5% match value is the shared-state cache hit rate. The 41% complete value also includes tasks that were already current in the build directory. In this example, 41% of the 5,266 relevant tasks were reusable or already current, but only 5% of the requested shared-state results came from the local cache.

The exact numbers vary between builds. Current does not by itself prove that the shared cache is working; look for a nonzero Local value.

Reuse depends on matching BitBake task signatures. Changes to recipes, configuration, dependencies, tools, or the build host can make an older cache entry incompatible. BitBake safely rebuilds that task instead of using an incompatible result.

Important Notes

• Keep each BSP workspace's build directory. The shared caches complement incremental build output; they do not replace it.

• Different BSP workspaces can share the same cache paths. Downloads are often reusable across platforms, while shared state is reused only when task signatures match.

• The caches grow over time. Check their size with:

  Development host

  du -sh "$HOME/bitbake/downloads" "$HOME/bitbake/sstate-cache"

• Do not modify or delete cache contents while a build is running. Removing cached data at another time is safe, but the next build must download or rebuild it.

• Existing workspace-local caches do not need to be migrated. New builds can start using the shared paths immediately and populate them as needed.

For more detail, see the Yocto Project's shared-state cache guidance.