Lesson

Tools for Setting up the System

Using kas and bitbake-setup to create reproducible Yocto build environments

The Yocto ProjectGetting StartedLesson 3 of 15

Once a Yocto project grows beyond a quick experiment, manually cloning repositories, checking out matching branches, editing bblayers.conf, and remembering local build settings becomes really hard to maintain.

The two main tools used to reduce that friction are kas and bitbake-setup. Neither replaces BitBake itself. They prepare and manage the build environment so that BitBake can run in a consistent, repeatable way.

Why Setup Tools Matter

These tools are useful because they let you describe the build environment as a configuration instead of as bespoke knowledge that can get lost in the mists of time.

This usually means:

defining which repositories are needed
selecting the matching branch, tag, or commit for each repository
enabling the layers required for the project
setting machine, distro, image target, and local build options
making it easier for another developer or a CI system to recreate the same setup

Without a setup tool, teams often fall back to large shell scripts or README files full of manual steps. That usually works for a while, but it becomes difficult to review, update, and understand as the project evolves.

Host Dependencies

Before using either tool, make sure you already have:

a supported Linux build host
the required host packages
enough disk space and RAM for a Yocto build

If you have not done that yet, go back to the system setup lesson.

`kas`

kas is a configuration-driven tool for BitBake-based projects, maintained by Siemens. It is widely used in product teams and CI systems because it gives you a single project file that can describe:

where to fetch repositories from
which layers to enable
which MACHINE and DISTRO to use
which image target to build
which snippets should be written into local.conf

Install `kas` with `pipx`

The current upstream documentation recommends pipx:

pipx install kas

That keeps the kas Python environment isolated from the rest of your system.

Structure of a `kas.yml` file

A typical file contains a header plus the project choices you want kas to write into the BitBake configuration.

machine: The value written to MACHINE, for example qemux86-64.
distro: The value written to DISTRO, for example poky or your own distro.
target: The BitBake target to build, such as core-image-minimal.
repos: The repositories kas should fetch, along with their URLs, revisions, and layers.
local_conf_header: Extra lines kas should write into local.conf, usually for cache directories or small local settings.

Example `kas.yml`

This is a small but realistic example for a reproducible starter build:

header:
  version: 18

machine: qemux86-64
distro: poky
target: core-image-minimal

repos:
  bitbake:
    url: "https://git.openembedded.org/bitbake"
    # Tag: yocto-6.0.2
    commit: "178b39316042fd71d46e82ba6889e3b824024bb0"

  openembedded-core:
    url: "https://git.openembedded.org/openembedded-core"
    branch: "wrynose"
    commit: "8ecd6056805602dc99c4cd110b04e39ae5424610"
    layers:
      meta:
  
  meta-yocto:
    url: "https://git.yoctoproject.org/meta-yocto"
    branch: "wrynose"
    commit: "c81e26bda0cacc3e13b1fee7a98faadc449841bc"
    layers:
      meta-poky:
      meta-yocto-bsp:

local_conf_header:
  development-only: |
    EXTRA_IMAGE_FEATURES:append = " allow-empty-password allow-root-login empty-root-password"
  cache: |
    DL_DIR = "${HOME}/yocto/shared/downloads"
    SSTATE_DIR = "${HOME}/yocto/shared/sstate-cache/${MACHINE}"
  output: |
    CONF_VERSION = "1"

This example does a few important things:

it selects a machine
it selects a distro
it sets a default image target
it declares the repositories and layers explicitly
it keeps cache configuration in the project file instead of a long setup script

Main `kas` commands

The core commands you will use most often are:

kas checkout kas.yml
kas build kas.yml
kas shell kas.yml

Use them like this:

kas checkout kas.yml: Fetches and checks out the repositories described by the configuration, but does not start a build.
kas build kas.yml: Prepares the build environment and runs the configured BitBake target. This is good for integrating into a CI system.
kas shell kas.yml: Opens a shell inside the prepared build environment so you can run manual commands such as bitbake, bitbake-layers, or runqemu. This is the typical use while developing.

For example:

kas shell kas.yml
bitbake core-image-minimal

`kas-container`

kas-container is a wrapper that runs kas inside a container image.

Use it when:

your host Linux distribution is older or inconsistent across developers
you want stronger isolation from host tools and Python packages
you want the same build wrapper locally and in CI
you need to reduce host contamination risk further than plain kas

Typical usage looks like:

kas-container build kas.yml
kas-container shell kas.yml
kas-container checkout kas.yml

`bitbake-setup`

bitbake-setup is the setup tool shipped with BitBake itself and documented by the Yocto Project.

It solves a similar problem to kas, but the workflow is different:

kas usually starts from a project-owned YAML file
bitbake-setup starts from a JSON configuration template
bitbake-setup can also work with a registry of templates and choices

In other words, bitbake-setup is closer to a BitBake-native setup framework, while kas is a standalone project tool that many teams adopt across products.

Where it lives

bitbake-setup is part of the BitBake source tree, which means it is available when you downloaded BitBake:

./bitbake/bin/bitbake-setup --help

Note the the design of the BitBake repository is that you clone that once to a sensible central place on your system and then use bitbake-setup to create your local working project.

Initial Setup

You can setup an initial build environment with the following command:

$ ./bitbake/bin/bitbake-setup init

By default, this will set up a top directory in the current directory.

BitBake setup will then ask (on the first run) for the configuration options.

Choose a configuration (for example, poky-master):

Available Configuration Templates:
1. oe-nodistro-master   OpenEmbedded - 'nodistro' basic configuration
2. oe-nodistro-&DISTRO_NAME_NO_CAP  OpenEmbedded - 'nodistro' basic configuration, release 6.0 'wrynose' (supported until ...)
3. poky-master          Poky - The Yocto Project testing distribution configurations and hardware test platforms
4. poky-&DISTRO_NAME_NO_CAP         Poky - The Yocto Project testing distribution configurations and hardware test platforms, release 6.0 'wrynose' (supported until ...)

Please select one of the above configurations by its number: 3

Depending on the choice above, new options can be prompted to further specify which configuration to use. For example:

Available bitbake configurations:
1. poky              Poky - The Yocto Project testing distribution
2. poky-with-sstate  Poky - The Yocto Project testing distribution with internet sstate acceleration. Use with caution as it requires a completely robust local network with sufficient bandwidth.

Please select one of the above bitbake configurations by its number: 1

Choose a target MACHINE (for example, qemux86-64):

Target machines:
1. machine/qemux86-64     x86-64 system on QEMU
2. machine/qemuarm64      ARMv8 system on QEMU
3. machine/qemuriscv64    RISC-V system on QEMU
4. machine/genericarm64   Arm64 SystemReady IR/ES platforms
5. machine/genericx86-64  x86_64 (64-bit) PCs and servers

Please select one of the above options by its number: 1

Choose a DISTRO (for example, poky):

Target distributions:
1. distro/poky         Yocto Project Reference Distro
2. distro/poky-altcfg  Poky alternative with systemd as init manager
3. distro/poky-tiny    Poky alternative optimized for size

Please select one of the above options by its number: 1

Choose a setup directory name:

Enter setup directory name: [poky-master]

Main `bitbake-setup` workflow

Start by initialising a setup from the template:

./layers/third-party/bitbake/bin/bitbake-setup init ./minimal-qemux86-64.conf.json

If you want to set shared download storage at the same time, use a documented setting:

./layers/third-party/bitbake/bin/bitbake-setup \
  --setting default dl-dir "${HOME}/yocto/shared/downloads" \
  init ./minimal-qemux86-64.conf.json

After that, enter the build environment by sourcing the generated script:

source ./<setup-directory>/build/init-build-env

Then run BitBake normally:

bitbake core-image-minimal

The other commands worth knowing are:

./layers/third-party/bitbake/bin/bitbake-setup list
./layers/third-party/bitbake/bin/bitbake-setup status --setup-dir ./<setup-directory>
./layers/third-party/bitbake/bin/bitbake-setup update --setup-dir ./<setup-directory>

Reproducibility with `bitbake-setup`

If a template tracks a branch instead of an exact commit, current bitbake-setup documentation explains that it records fixed revisions in sources-fixed-revisions.json.

That gives you a practical way to:

start from a branch-based template while developing
capture the exact tested revisions
reuse those fixed revisions later for a repeatable rebuild

Choosing Between Them

The important thing to remember is that neither tool replaces BitBake. They help you create and manage the environment around BitBake.

`kas`

Choose kas when:

you want a compact project-owned YAML file
your team already uses kas in CI
you want an easy path to containerised builds with kas-container
you want a widely used cross-project workflow

`bitbake-setup`

Choose bitbake-setup when:

you want to stay close to the BitBake-native workflow
you want to use BitBake’s template and registry model
you want setup management that follows the tool shipped with your BitBake branch

Short practical guidance

For many product teams, kas feels simpler to adopt quickly.

For teams that want a more BitBake-native template system, or that are standardising around features documented directly in the BitBake manual, bitbake-setup can be a very good fit.

Summary

kas and bitbake-setup both help you manage the messy part of a Yocto project: repositories, layers, revisions, and local build configuration.

these tools prepare the environment; BitBake still does the build
setup should live in reviewed configuration, not in long manual scripts
branch alignment matters across all Yocto layers
exact revisions improve reproducibility
controlled environments are useful, but they make implicit host settings less reliable

Question 1What problem do `kas` and `bitbake-setup` solve?

They prepare and manage the Yocto build environment consistentlyThey replace BitBake as the build engineThey generate kernel drivers automatically

Question 2When is `kas-container` especially useful?

When you want stronger isolation from host-tool differencesWhen you need a faster replacement for `bitbake`When you want to avoid creating any configuration files

Question 3What is a good reason to pin exact revisions in a setup tool configuration?

To make the build reproducible across machines and over timeTo stop BitBake from creating `tmp/`To avoid having a `local.conf` file

Why Setup Tools Matter

Host Dependencies

kas

Install kas with pipx

Structure of a kas.yml file

Example kas.yml

Main kas commands

kas-container

bitbake-setup

Where it lives

Initial Setup

Main bitbake-setup workflow

Reproducibility with bitbake-setup

Choosing Between Them

kas

bitbake-setup

Short practical guidance

Summary

Quick quiz: setup tools

`kas`

Install `kas` with `pipx`

Structure of a `kas.yml` file

Example `kas.yml`

Main `kas` commands

`kas-container`

`bitbake-setup`

Main `bitbake-setup` workflow

Reproducibility with `bitbake-setup`

`kas`

`bitbake-setup`