KAS(1)

📦
version 5.4 · 6 versions
, in ubuntu stonking

KAS(1) — kas 💅✨

okay so bestie, meet kas — the setup tool for bitbake based projects. the vibe is lowkey “let me handle the annoying setup so you can go build.” 🫶

✨ NAME ✨

kas — a setup tool for bitbake based projects.

🌸 SYNOPSIS 🌸

kas [-h] [--version] [-l {debug,info,warning,error,critical}]
    {build,checkout,clean,cleansstate,cleanall,purge,diff,dump,for-all-repos,lock,menu,shell} ...

💖 DESCRIPTION 💖

kas — setup tool for bitbake based project. it’s giving “I got you, bestie.” ✨

This tool provides an easy mechanism to setup bitbake based projects.

The OpenEmbedded tooling support starts at step 2 with bitbake. The downloading of sources and then configuration has to be done by hand. Usually, this is explained in a README. Instead kas is using a project configuration file and does the download and configuration phase.

Key features provided by the build tool:

  • clone and checkout bitbake layers
  • create default bitbake settings (machine, arch, ...)
  • launch minimal build environment, reducing risk of host contamination
  • initiate bitbake build process

🎀 OPTIONS 🎀

👑 Positional Arguments

  • cmd — Possible choices: build, checkout, clean, cleansstate, cleanall, purge, diff, dump, for-all-repos, lock, menu, shell

🌈 Named Arguments

  • --version — show program's version number and exit
  • -l='info', --log-level='info' — Set log level (default: info)
    • Possible choices: debug, info, warning, error, critical

🛠️ SUB-COMMANDS 🛠️

pick your fighter, bestie 💅

kas build 🔥

kas build [-h] [--skip STEP] [--force-checkout] [--update] [-k]
          [--target TARGET] [-c TASK] [--provenance {true,mode=min,mode=max}]
          [config] [extra_bitbake_args ...]

Checks out all necessary repositories and builds using bitbake as specified in the configuration file.

kas checkout ✨

kas checkout [-h] [--skip STEP] [--force-checkout] [--update] [config]

Checks out all necessary repositories and sets up the build directory as specified in the configuration file.

kas clean 🧼

kas clean [-h] [--dry-run] [--isar-privileged | --isar-rootless] [config]

Clean build artifacts, keep sstate cache and downloads.

kas cleansstate 🧽

kas cleansstate [-h] [--dry-run] [--isar-privileged | --isar-rootless] [config]

Clean build artifacts and sstate cache.

kas cleanall 💥

kas cleanall [-h] [--dry-run] [--isar-privileged | --isar-rootless] [config]

Clean build artifacts, sstate-cache and downloads.

kas purge 🚮

kas purge [-h] [--dry-run] [--isar-privileged | --isar-rootless] [--preserve-repo-refs] [config]

Purge all data managed by kas, including managed repos.

kas diff 🆚

kas diff [-h] [--skip STEP] [--force-checkout] [--update] [--format {json,text}] [--oneline] [--no-color] [--commit-only] [--content-only] config1 config2

Compare two kas configurations.

kas dump 📤

kas dump [-h] [--skip STEP] [--force-checkout] [--update] [--indent INDENT] [--sort] [--format {yaml,json}] [--resolve-refs] [--resolve-local] [--resolve-env | --lock] [config]

Expand and dump the final config to stdout. When resolving branches, this is done before patches are applied.

kas for-all-repos 🔁

kas for-all-repos [-h] [--skip STEP] [--force-checkout] [--update] [-E] [-k] [config] command

Runs a specified command in all checked out repositories.

kas lock 🔒

kas lock [-h] [--skip STEP] [--force-checkout] [--update] [--indent INDENT] [--sort] [config]

Create and update kas project lockfiles.

kas menu 📋

kas menu [-h] [kconfig]

Provides a configuration menu and triggers the build of the choices.

kas shell 🐚

kas shell [-h] [--skip STEP] [--force-checkout] [--update] [-E] [-k] [-c COMMAND] [config]

Run a shell in the build environment.

📁 PROJECT CONFIGURATION 📁

The project configuration file describes the build environment and the layers to be used. It is the main input to kas. For details, see kas-project-config(1).

🧾 BUILD ATTESTATION 🧾

Kas supports to generate build attestation. For details, see kas-build-attestation(1).

🔐 CREDENTIAL HANDLING 🔐

kas provides various mechanisms to inject credentials into the build. For details, see kas-credentials(1).

🌱 ENVIRONMENT VARIABLES 🌱

kas uses a number of environment variables to configure its behavior. The Variables Glossary provides an overview, wherein the tuple (C,K,E) denotes the scope of the variable.

By default, kas does not inherit the full host shell environment into the build environment. Instead, kas constructs a controlled environment to improve reproducibility and reduce host contamination.

How additional environment variables are handled depends on their scope and on the selected sub-command. Where supported, variables can be defined in the kas configuration or preserved explicitly from the host environment, for example with -E/--preserve-env.

When using kas-container, this is more limited, especially for variables that contain file or directory paths, because the container may use a different directory layout.

All directories that are passed to kas by setting the corresponding environment variables (e.g. KAS_WORK_DIR, KAS_BUILD_DIR, ...) must not overlap with each other, except for overlapping with KAS_WORK_DIR (i.e. the build|sstate|downloads|repo-ref dirs can be below the work dir). Environment variables that reference a file or directory must have a valid path that is accessible and readable.

🔎 Variable Scope 🔎

kas-container (C)

The variable is processed or forwarded by the kas-container script. For some variables, the variable is re-written to the container's directory layout.

Note: The env section of the project configuration can be used to make arbitrary environment variables available to the build environment. When invoking the build via kas-container, make sure to also forward the corresponding environment variables into the container.

kas (K)

The variable is processed by kas itself. Some variables (e.g. the credentials for the awscli) are re-written to configuration files to also support older versions of the tooling.

build environment (E)

The variable is exported into the build environment. In this environment, the bitbake command is executed.

config-file (c)

The variable can be set in the env section of the Project Configuration <#project-configuration-label>. Note, that a value provided by the calling environment takes precedence over the value in the configuration file.

💫 Variables Glossary 💫

Okay bestie, so these env vars get processed before the config file is even read (unless it says otherwise somewhere in here). Which means — plot twist — you literally cannot define them or overwrite them using the env section of the config file. They're locked in. Periodt. 🔒

  • KAS_WORK_DIR (C, K) — the path of the kas work directory. Defaults to your current working directory. Heads up: if you set this, the directory has to already exist. kas is not your mom, it will not create it for you. 💅
  • KAS_BUILD_DIR (C, K) — the path of the build directory. Defaults to ${KAS_WORK_DIR}/build. If you set it, the parent directory must exist. Also kas drops a CACHEDIR.TAG in there, so like, your backup tool knows what's up. 🎀
  • KAS_REPO_REF_DIR (C, K) — the path to the repository reference directory. Repos sitting in this directory get used as references when cloning. For kas to actually find them they need to be named a very specific way, and the repo URLs get translated like this:

https://github.com/siemens/meta-iot2000.git resolves to the name github.com.siemens.meta-iot2000.git.

Repos that aren't found just get cloned below this directory instead. And here's the slay part: multiple instances of kas can work on the same directory simultaneously, as long as the underlying filesystem is POSIX compatible. Iconic. ✨ This directory must exist if set.

  • KAS_DISTRO KAS_MACHINE KAS_TARGET KAS_TASK (C, K) — these overwrite the respective setting in the configuration file. Big main character energy, they just take over. 👑
  • KAS_PREMIRRORS (C, K) — specifies alternatives for repo URLs. Just like bitbake PREMIRRORS, this variable is made of new-line separated entries. Each entry defines a regular expression to match a URL and, space-separated, its replacement. E.g.:
http://.*\.someurl\.io/ http://localmirror.net/
  • DISTRO_APT_PREMIRRORS (C,c) — specifies alternatives for apt URLs. Just like KAS_PREMIRRORS. Same vibe, apt edition. 🍓
  • KAS_CLONE_DEPTH (C, K) — does a shallow git clone/fetch using --depth=N where N is whatever you put in this variable. Lowkey perfect for CI, when the work directory always starts empty and then gets yeeted after every run anyway. 💀
  • SSH_PRIVATE_KEY (K) — variable containing the private key that should be added to an internal ssh-agent. Girl, this key cannot be password protected. Useful for CI build servers. On desktop machines tho, an ssh-agent running outside the kas environment is more useful.
  • SSH_PRIVATE_KEY_FILE (K) — path to the private key file that should be added to an internal ssh-agent. Same deal: this key cannot be password protected. Useful for CI build servers. On desktop machines, an ssh-agent running outside the kas environment is more useful.
  • SSH_AUTH_SOCK (C,K,E) — SSH authentication socket. Used for cloning over SSH, and it's the alternative to SSH_PRIVATE_KEY or SSH_PRIVATE_KEY_FILE. Take your pick bestie 🫶
  • DL_DIR SSTATE_DIR SSTATE_MIRRORS (C,K,E,c) — environment variables that get transferred to the bitbake environment. And the DL_DIR and SSTATE_DIR directories are created along with their parents, if set. So these ones kas will actually make for you. Make it make sense 😭
  • TMPDIR (K,E,c) — directory for temporary files.
  • http_proxy https_proxy ftp_proxy no_proxy (C,K,E) — these define the proxy configuration bitbake should use.
  • GIT_PROXY_COMMAND (E) NO_PROXY (C,K,E) — set proxy for native git fetches. NO_PROXY is evaluated by OpenEmbedded's oe-git-proxy script. Ngl, very specific but very important. 🔥
  • SHELL (C,K,E) — the shell to start when using the shell plugin and in the bitbake environment.
  • TERM (C,K,E) — the terminal options used in the shell plugin and in the bitbake environment.
  • TZ (C) — timezone settings. ⌚
Also a lil reminder because I know someone's gonna forget: that whole (C), (K), (E), (c) notation is doing heavy lifting here, and the letters that apply to each variable are exactly the ones listed above. Don't skip 'em. 💜
  • AWS_CONFIG_FILE, AWS_ROLE_ARN, AWS_SHARED_CREDENTIALS_FILE, AWS_WEB_IDENTITY_TOKEN_FILE (K,C) — these are all just paths to the awscli configuration and credentials files, and they get copied straight into the kas home dir. 🌈 Comfy.
  • GIT_CREDENTIAL_HELPER, GIT_CREDENTIAL_USEHTTPPATH (K,C) — these let you set and configure the git credential helper inside the .gitconfig of the kas user. Your git auth setup, but make it kas-shaped. 💅
  • KAS_GIT_CREDENTIAL_STORE (C) — path to a git credential store file on the host. The moment you set it, the file gets bind-mounted into the container read-only and the git credential store helper is configured to use it. It's the exact same thing as --git-credential-store. 🫶
  • KAS_GIT_CREDENTIAL_SOCKET (C) — path to the git credential cache daemon socket on the host. Set it and the socket gets bind-mounted into the container, and the git credential cache helper is configured to use it. Same energy as --git-credential-socket. 🔌
  • GITCONFIG_FILE (K,C) — path to a .gitconfig file which will be copied to the kas home dir as .gitconfig. Slay, same name and everything.
  • NETRC_FILE (K,C) — path to a .netrc file which will be copied to the kas home dir as .netrc. 🙈
  • NPMRC_FILE (K,C) — path to a .npmrc file which will be copied to the kas home dir as .npmrc. Not me giving npm a whole personality. 🍓
  • REGISTRY_AUTH_FILE (K,C) — path to a container registry authentication file.
  • CI_SERVER_HOST, CI_SERVER_PORT, CI_SERVER_PROTOCOL, CI_SERVER_SHELL_SSH_HOST, CI_SERVER_SHELL_SSH_PORT, CI_JOB_TOKEN, CI_JOB_URL, CI_REGISTRY, CI_REGISTRY_USER (K) — env vars straight outta GitLab CI. If they're set, .netrc is configured to allow fetching from the GitLab instance, and an entry gets appended in case NETRC_FILE was given as well.
heads up though — if the file already contains an entry for that host, most tools would probably take that first one. 😭 First come, first served, no cap.

The job URL is added to the provenance attestation (if enabled). And if CI_REGISTRY and CI_REGISTRY_USER are also set, a container registry login file gets created, which is used by docker, podman and skopeo. In case REGISTRY_AUTH_FILE was given as well, the CI login data will be appended to that file. The required base64 encoded login data is generated by kas, bestie — you don't gotta do it yourself. ✨

  • GITHUB_ACTIONS, GITLAB_CI (K) — environment variables from GitHub actions or GitLab CI. If set to true, .gitconfig is automatically imported. For details, see GITCONFIG_FILE. Obsessed with a self-configuring setup fr fr. 🎀
  • REMOTE_CONTAINERS (K), REMOTE_CONTAINERS_<x> (K,E) — environment variables related to VSCode Remote Containers. If you're running in this environment, .gitconfig is automatically imported. Devcontainers girlies stay winning. 🦋
  • BB_NUMBER_THREADS, PARALLEL_MAKE (C,K,E) — environment variables to control the concurrency. Go faster, queen. 🔥
  • KAS_IMAGE_VERSION (C) — select the version of the (official) kas container, e.g. 4.5. 👑
  • KAS_CONTAINER_IMAGE_DISTRO (C) — select the base distro and its release of the container image, e.g. debian-bookworm. If not specified, the default (most-recent supported) distro version is used. If it ain't broke, don't pick it. 💜
  • KAS_CONTAINER_IMAGE (C) — select the container image (full OCI path including tag).
  • KAS_CONTAINER_ENGINE (C) — explicitly set the container engine, either docker or podman. If not set, this is auto-detected (preference: docker).
  • KAS_SUDO_CMD (C) — explicitly set the sudo command, either sudo or run0, for operations that require higher privileges. If not set, this is auto-detected (preference: sudo).
note that run0 does not preserve the environment and cannot setup loopback devices. 💀 So like, know that going in.
  • KAS_BUILDTOOLS_DIR (C,K) — explicitly set the path where kas will download and install buildtools. If not set, kas will use KAS_BUILD_DIR/buildtools as the default path. ✨

🌈 SEE ALSO 🌈

Go read those too bestie, iykyk. 📚

👑 KAS 👑

Part of the kas(1) suite.

🎀 Author 🎀

Daniel Wagner, Jan Kiszka, Claudius Heine

Siemens and contributors, 2017-2025

okay that's literally the whole entire page, and you ate it up. this was kas 5.4, served fresh on Jun 25, 2026 — periodt. go build something iconic, bestie 💅🌸

🫶 bye!!

📦 where this page comes from