The Evolving Landscape of Yocto Project Setup: Bitbake-Setup vs. KAS

Full disclosure: As a long-term user and a contributor to KAS, my personal opinions here are inherently biased, though I have kept the technical facts as accurate and objective as possible.

Anyone who has ever used Yocto to create a custom Linux distribution has probably observed that the Yocto Project itself doesn’t offer a standardized method for the very first step: fetching all necessary layers and establishing the initial build configuration. Since 2017, the KAS tool has effectively filled this void. Today in 2025, KAS boasts a substantial user base and a thriving community. However, it remains neither an official part of the Yocto Project nor the officially recommended tool for project setup. Since 2024, the Yocto Project has been developing its own tool, bitbake-setup. Now, in late 2025, this new tool has begun to materialize.

As Linux consultants, we frequently receive questions from clients regarding the status and future direction of Yocto project setup. Especially after bitbake-setup became available, we were questioned what will happen to KAS, what to expect from bitbake-setup and so on. This blog post aims to summarize the current situation and clarify the key differences and implications of using KAS versus bitbake-setup.

KAS: Origins and a Brief Overview

Before the emergence of KAS¹ (Bavarian dialect for cheese), Yocto users typically managed layer dependencies using either git submodules or the repo² tool. This approach often relied on a collection of shell scripts to generate fundamental configuration files like bblayers.conf and local.conf. This process was frequently cumbersome and highly error-prone.

Engineers at Siemens recognized this lack of standardization as a risk to the quality of their build infrastructure and began to look for a solution. This effort led to the initial concepts behind KAS. The core principle behind KAS is to describe a Yocto project in a YAML configuration file to enable deterministic builds. The goal is simple: regardless of where you run the build, the output should be identical. KAS carefully controls the build environment, ensuring that no environment variables from the host system are inherited into the build unless explicitly specified within the KAS configuration file. Crucially, KAS works as an external tool with Yocto. Although it essentially wraps the standard Yocto process into a deterministic environment and generates all necessary configuration files, Yocto does not need to be aware of KAS in any way.

In addition to its core functionality, KAS also provides a wrapper script, kas-container, which allows developers to execute the entire project setup and build process inside a container using Docker or Podman. This containerization offers excellent isolation from the host system. By default, the KAS build container uses a minimal Debian Linux installation with only the host dependencies strictly required by the Yocto Project installed. This ensures that every build runs within a fully deterministic environment, further strengthening KAS’s promise of reproducible results.

Here is an example of a typical KAS configuration file:

This file describes:

• Which repositories (layers) to fetch and the exact git commit to use.
• The default machine, distro, and target image for the build.
• Extra variables to append to the resulting local.conf file.

To build the project, you execute the command kas build rpi.yml. If you want the entire process to run within a container for maximum host isolation, you use the wrapper: kas-container build rpi.yml.

When you run KAS, it performs the following steps:

• Check out all listed repositories.
• Generate the bblayers.conf file.
• Generate the local.conf file.
• Execute the main build command, here bitbake -c build core-image-minimal.

When you use kas-container, KAS runs entirely inside the container. The host system only needs the kas-container shell script and either Docker or Podman installed.

Beyond project setup and building, KAS offers various other subcommands to streamline Yocto development. The most notable include:

• shell: Opens a shell within the sanitized build environment, useful for debugging or running custom bitbake commands.
• menu: Provides an interactive interface to configure the project and set build variables.
• diff: Compares two KAS configuration files and shows the git log of each referenced repository
• lock: Used for supply chain hardening, think of it like the lock file mechanism offered by Go, Cargo, or Node.js.

For more details on KAS, please refer to the documentation or this talk from Jan Kiskza.

bitbake-setup: The Yocto Project’s Official Solution

While KAS is permissively licensed under the MIT license and its developers have repeatedly expressed willingness to integrate KAS closely to the Yocto Project, these efforts never materialized.³⁴ Early on, Yocto developers stated that a setup tool like KAS should be an integrated component of bitbake, not a separate project. One argument to have such a tool as part of bitbake is that the bitbake fetch code can get re-used instead of executing git commands directly as KAS does currently. This position directly led to the development of bitbake-setup.

As its name suggests, bitbake-setup resides directly within the bitbake repository. Therefore, the very first step in setting up and building a Yocto system using this tool is cloning the bitbake git repository itself.

A typical bitbake-setup workflow looks like this:

• git clone -b master-next https://git.openembedded.org/bitbake
• bitbake/bin/bitbake-setup init rpi.conf.json
• . /path/to/your/builddir/init-build-env
• bitbake core-image-minimal

If you omit the parameter when running bitbake-setup init, it uses a default configuration. However, you will typically pass the name, a path or URL pointing to your configuration.

Here is an example of a simple bitbake-setup JSON configuration file:

The configuration file defines key project parameters, primarily:

• Which repositories (layers) to fetch.
• The available configurations, here distributions (DISTRO) and machines (MACHINE).

Like the kas menu command, bitbake-setup can prompt the user for configuration choices. For instance, based on the loaded configuration, it offers multiple options for the desired machine and distribution. However, the user interface differs: while KAS uses a Kconfig menu Text User Interface (TUI), bitbake-setup asks questions and collects input directly via the console.

Example output of bitbake-setup when asking questions:

bitbake-setup maintains a top-level directory, by default ~/bitbake-builds/. This directory hosts shared resources, including a downloads folder, global settings, build configurations, and the initialized Yocto projects. When you set up multiple projects using bitbake-setup, they automatically share the download folder because bitbake-setup pre-configures the DL_DIR variable. Additionally, bitbake-setup uses a registry to store build configurations. The default registry is located within the bitbake repository, but you can define a custom one.

For example, to set a new default registry, run bitbake-setup settings set default registry /path/to/my/bbregistry.

After placing your *.conf.json files into /path/to/my/bbregistry/configurations/, commands like bitbake-setup list and bitbake-setup init will recognize them.

$ bitbake-setup list Loading settings from /home/bobthebuilder/bitbake-builds/settings.conf Bitbake-setup is using /home/bobthebuilder/bitbake-builds as top directory ("bitbake-setup settings --help" shows how to change it). Available configurations: rpi Raspberry Pi base config base A Yocto base configuration with options xxx Just testing Run 'init' with one of the above configuration identifiers to set up a build.

So, by passing a configuration name to bitbake-setup init instead of a filename or an URL, it will lookup the configuration from the registry.

The incorporation of bitbake-setup into the bitbake repository has significant implications for how Yocto projects are fetched. Recall that the Poky repository has traditionally served as the official reference system, bundling three core components: bitbake, meta-yocto, and openembedded-core. Since bitbake-setup requires you to clone the standalone bitbake repository first, the historical role of the monolithic Poky repository is diminished. Users can now fetch openembedded-core and meta-yocto individually alongside bitbake. Consequently, for future Yocto releases, the Poky repository will no longer receive updates, users are advised to fetch the repositories individually.

How to apply this change to a KAS based project can be observed in this change: https://github.com/mendersoftware/meta-mender-community/commit/f82d2d4a9ebc79ac3e88e6388609e4ec8e49a7e6.

For more details on bitbake-setup, please refer to these two talks from Alexander Kanavin.

Comparing bitbake-setup and KAS

Comparing these two tools is more complex than one might initially expect. Both KAS and bitbake-setup have distinct origins. KAS essentially comes from users for users, while bitbake-setup reflects the perspective of Yocto developers. Yocto developers used this tool as an opportunity to implement long-standing tasks, such as untangling the Poky repository, implementing configuration fragments, and creating a setup tool tightly coupled with bitbake.

A key technical contrast with KAS is that bitbake-setup uses JSON for its configuration format, not YAML. While JSON is excellent as a serialization format, using it for human-edited configuration files introduces two main usability constraints:

• JSON does not support comments, which can hinder documentation
• It does not allow trailing commas, leading to potential parsing errors during manual edits

Therefore, we at sigma star gmbh, believe that JSON is less ideal for user-facing configuration files.

Another difference in philosophy is how the two tools manage the local.conf file. KAS automatically populates the local.conf file based on the settings defined in its YAML configuration. bitbake-setup does not automatically fill your local.conf. The reasoning behind this approach is that local.conf should contain only user-specific settings and overrides, preventing it from being polluted by auto-generated content.

For instance, the KAS example above would yield a local.conf that looks like this:

In contrast, local.conf as generated by bitbake-setup:

# # This file is intended for local configuration tweaks. # # If you would like to publish and share changes made to this file, # it is recommended to put them into a distro config, or to create # layer fragments from changes made here. #

Since bitbake-setup lets you select a distribution and machine but does not fill local.conf, Yocto developers have introduced a more generic concept: layer fragments. Layer fragments are files that contain variables and their corresponding values. You select these files during project setup, and the system inserts their contents directly into the global variable space. Fragment selection uses the new file toolcfg.conf and the variable OE_FRAGMENTS. For instance, in our example the system always pulls core/yocto/sstate-mirror-cdn.conf. And pulls distro/poky.conf plus machine/raspberrypi5.conf based on the user’s selection.

toolcfg.conf:

The configuration of other settings, such as the download directory path (DL_DIR), also differs. KAS sets DL_DIR as an environment variable and adds it to BB_ENV_PASSTHROUGH_ADDITIONS, ensuring bitbake utilizes the DL_DIR value from the environment. Conversely, bitbake-setup injects the DL_DIR variable directly into the bitbake code parser cache.

As mentioned, bitbake-setup and KAS use different configuration formats. They also handle these configurations differently. bitbake-setup strictly uses a single configuration file. In contrast, KAS offers mechanisms to include or layer multiple configuration files. This can be achieved either via the includes property within a configuration file or directly at the command line, e.g. kas build rpi.yml:sigmastar-settings.yml. This layering feature is useful for maintaining large, complex build configurations where different Yocto setups share many settings. It also allows for overriding specific values, such as customer-specific settings (e.g., URLs for internal git repositories). At sigma star gmbh, we use this mechanism frequently to override customer-specific settings, such as URLs for internal git repositories. This is necessary, for example, when direct access to a customer’s internal network is unavailable and we must maintain a mirror of their git repos. For the curious reader, this git repository exhibits a non-trivial KAS configuration used at Siemens: https://github.com/siemens/meta-iot2050/.

Furthermore, a crucial difference from KAS is that bitbake-setup performs no host isolation. It checks out sources and configures Yocto but leaves it to the user to source the build environment and execute the desired bitbake command. While the Yocto Project has significantly improved its resilience to host contamination in recent years, issues still can occur. For projects prioritizing reproducibility, cheap container-based isolation remains a valuable safeguard. That said, we expect to see support for containerized builds, like kas-container provides, at some point. However, this does not seem to have priority⁵.

Finally, since bitbake-setup is in an early stage of development, it currently lacks robust error handling. Users may encounter unhandled Python exceptions when the tool faces errors, such as semantically incorrect configurations or unreachable network resources. However, I am optimistic that this will be improved in the near future.

Summary

Essentially, bitbake-setup and KAS share many features but approaches them differently. The most significant difference is that bitbake-setup is deeply integrated into Yocto, whereas KAS is not. bitbake-setup is still in an early development stage, so more features and changes are expected. We expect bitbake-setup to gain a significant user base in the coming years, particularly once it is documented in the official Yocto materials. As of today, KAS is more mature and feature-rich than bitbake-setup, so we will continue to recommend KAS to all our customers. KAS will remain functional regardless of the direction in which bitbake-setup evolves because it does not require Yocto awareness.

We believe that both KAS and bitbake-setup can benefit from each other, one possible scenario we can think of is that bitbake-setup becomes usable as a plugin from KAS to fetch and set up all layers, while KAS allows building the project with just one command and a simple configuration file. We also expect that KAS will utilize layer fragments sooner or later.

From the users’ perspective, this sadly seems like a missed opportunity for collaboration. Hopefully, both the underlying reasons and the mutual benefits will become visible in the long run.