--- name: "kas" section: "1" platform: "linux" package: "kas" version: "4.8.1-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/kas" --- # kas(1) a setup tool for bitbake based projects ## 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 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** sub command help 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 - **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 \[-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 \[-h\] \[--dry-run\] \[--isar\] \[config\]** Clean build artifacts, keep sstate cache and downloads. - **kas cleansstate \[-h\] \[--dry-run\] \[--isar\] \[config\]** Clean build artifacts and sstate cache. - **kas cleanall \[-h\] \[--dry-run\] \[--isar\] \[config\]** Clean build artifacts, sstate-cache and downloads. - **kas purge \[-h\] \[--dry-run\] \[--isar\] \[--preserve-repo-refs\] \[config\]** Purge all data managed by kas, including managed repos. - **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 \[-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 \[-h\] \[--skip STEP\] \[--force-checkout\] \[--update\] \[-E\] \[-k\]** **\[config\] command** Runs a specified command in all checked out repositories. - **kas lock \[-h\] \[--skip STEP\] \[--force-checkout\] \[--update\] \[--indent INDENT\]** **\[--sort\]**\ **\[config\]** Create and update kas project lockfiles. - **kas menu \[-h\] \[kconfig\]** Provides a configuration menu and triggers the build of the choices. - **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)](/kas-project-config/1.md)** ## BUILD ATTESTATION Kas supports to generate build attestation. For details, see **[kas-build-attestation(1)](/kas-build-attestation/1.md)**. ## CREDENTIAL HANDLING kas provides various mechanisms to inject credentials into the build. For details, see **[kas-credentials(1)](/kas-credentials/1.md)**. ## 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. 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*. Note, that a value provided by the calling environment takes precedence over the value in the configuration file. ### Variables Glossary These environment variables are processed before the configuration file is read (except if stated otherwise). By that, they cannot be defined or overwritten using the **env** section of the config file. | | | | --- | --- | | Environment variables | Description | | **KAS\_WORK\_DIR** (C, K) | The path of the kas work directory, current work directory is the default. This directory must exist if set. | | **KAS\_BUILD\_DIR** (C, K) | The path of the build directory, **${KAS\_WORK\_DIR}/build** is the default. The parent directory must exist if set. | | **KAS\_REPO\_REF\_DIR** (C, K) | The path to the repository reference directory. Repositories in this directory are used as references when cloning. In order for kas to find those repositories, they have to be named in a specific way. The repo URLs are translated like this: **https://github.com/siemens/meta-iot2000.git** resolves to the name **github.com.siemens.meta-iot2000.git**. Repositories that are not found will be cloned below this directory. Multiple instances of kas can simultaneously work on the same directory, as long as the underlying filesystem is POSIX compatible. This directory must exist if set. | | **KAS\_DISTRO** **KAS\_MACHINE** **KAS\_TARGET** **KAS\_TASK** (C, K) | This overwrites the respective setting in the configuration file. | | **KAS\_PREMIRRORS** (C, K) | Specifies alternatives for repo URLs. Just like bitbake **PREMIRRORS**, this variable consists 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**. | | **KAS\_CLONE\_DEPTH** (C, K) | Perform shallow git clone/fetch using --depth=N specified by this variable. This is useful in case CI always starts with empty work directory and this directory is always discarded after the CI run. | | **SSH\_PRIVATE\_KEY** (K) | Variable containing the private key that should be added to an internal ssh-agent. This key cannot be password protected. This setting is useful for CI build servers. On desktop machines, 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. This key cannot be password protected. This setting is 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 (alternative to **SSH\_PRIVATE\_KEY** or **SSH\_PRIVATE\_KEY\_FILE**). | | **DL\_DIR** **SSTATE\_DIR** **SSTATE\_MIRRORS** (C,K,E,c) | Environment variables that are transferred to the bitbake environment. The **DL\_DIR** and **SSTATE\_DIR** directories are created along with their parents, if set. | | **TMPDIR** (K,E,c) | Directory for temporary files. | | **http\_proxy** **https\_proxy** **ftp\_proxy** **no\_proxy** (C,K,E) | These variables 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. | | **SHELL** (C,K,E) | The shell to start when using the *shell* plugin. | | **TERM** (C,K,E) | The terminal options used in the *shell* plugin. | | **TZ** (C) | Timezone settings. | | **AWS\_CONFIG\_FILE** **AWS\_ROLE\_ARN** **AWS\_SHARED\_CREDENTIALS\_FILE** **AWS\_WEB\_IDENTITY\_TOKEN\_FILE** (K,C) | Path to the awscli configuration and credentials files that are copied to the kas home dir. | | **GIT\_CREDENTIAL\_HELPER** **GIT\_CREDENTIAL\_USEHTTPPATH** (K,C) | Allows one to set and configure the git credential helper in the *.gitconfig* of the kas user. | | **GITCONFIG\_FILE** (K,C) | Path to a *.gitconfig* file which will be copied to the kas home dir as *.gitconfig*. | | **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. | | **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) | Environment variables from GitLab CI, if set .netrc is configured to allow fetching from the GitLab instance. An entry will be appended in case **NETRC\_FILE** was given as well. Note that if the file already contains an entry for that host most tools would probably take that first one. The job URL is added to the provenance attestation (if enabled). If **CI\_REGISTRY** and **CI\_REGISTRY\_USER** is also set, a container registry login file is 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. | | **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**. | | **REMOTE\_CONTAINERS** (K) **REMOTE\_CONTAINERS\_\** (K,E) | Environment variables related to VSCode Remote Containers. If running in this environment, *.gitconfig* is automatically imported. | | **BB\_NUMBER\_THREADS** **PARALLEL\_MAKE** (C,K,E) | Environment variables to control the concurrency. | | **KAS\_IMAGE\_VERSION** (C) | Select the version of the (official) kas container (e.g. 4.5). | | **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). | ## SEE ALSO **[kas-project-config(1)](/kas-project-config/1.md)**, **[kas-build(1)](/kas-build/1.md)**, **[kas-credentials(1)](/kas-credentials/1.md)** ## KAS Part of the **[kas(1)](/kas/1.md)** suite. ## AUTHOR Daniel Wagner, Jan Kiszka, Claudius Heine ## COPYRIGHT Siemens and contributors, 2017-2025