Install Now
kas - a setup tool for bitbake based projects
Contents
Build Attestation
Kas supports to generate build attestation. For details, see kas-build-attestation(1).
Copyright
Siemens AG, 2017-2024
4.7 Feb 03, 2025 KAS(1)
Credential Handling
kas provides various mechanisms to inject credentials into the build. For details, see
kas-credentials(1).
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
Environment Variables
kas uses a number of environment variables to configure its behavior. The VariablesGlossary 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).
VariableScopekas-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 projectconfiguration 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.
buildenvironment(E)
The variable is exported into the build environment. In this environment, the bitbake command is
executed.
VariablesGlossary
┌───────────────────────────────────────┬──────────────────────────────────────────────┐
│ 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_DISTROKAS_MACHINEKAS_TARGET │ This overwrites the respective setting in │
│ KAS_TASK (C, K) │ 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) │ 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_DIRSSTATE_DIRSSTATE_MIRRORS │ Environment variables that are transferred │
│ (C,K,E) │ to the bitbake environment. The DL_DIR and │
│ │ SSTATE_DIR directories are created along │
│ │ with their parents, if set. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ TMPDIR (K,E) │ Directory for temporary files. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ http_proxyhttps_proxyftp_proxy │ These variables define the proxy │
│ no_proxy (C,K,E) │ configuration bitbake should use. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ GIT_PROXY_COMMAND (E) NO_PROXY │ Set proxy for native git fetches. NO_PROXY │
│ (C,K,E) │ 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. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ AWS_CONFIG_FILEAWS_ROLE_ARN │ Path to the awscli configuration and │
│ AWS_SHARED_CREDENTIALS_FILE │ credentials files that are copied to the kas │
│ AWS_WEB_IDENTITY_TOKEN_FILE (K,C) │ home dir. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ GIT_CREDENTIAL_HELPER │ Allows one to set and configure the git │
│ GIT_CREDENTIAL_USEHTTPPATH (K,C) │ 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. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ REGISTRY_AUTH_FILE (K,C) │ Path to a container registry authentication │
│ │ file. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ CI_SERVER_HOSTCI_SERVER_PORT │ Environment variables from GitLab CI, if set │
│ CI_SERVER_PROTOCOL │ .netrc is configured to allow fetching from │
│ CI_SERVER_SHELL_SSH_HOST │ the GitLab instance. An entry will be │
│ CI_SERVER_SHELL_SSH_PORTCI_JOB_TOKEN │ appended in case NETRC_FILE was given as │
│ CI_JOB_URLCI_REGISTRY │ well. Note that if the file already contains │
│ CI_REGISTRY_USER (K) │ 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_ACTIONSGITLAB_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) │ Environment variables related to VSCode │
│ REMOTE_CONTAINERS_<x> (K,E) │ Remote Containers. If running in this │
│ │ environment, .gitconfig is automatically │
│ │ imported. │
├───────────────────────────────────────┼──────────────────────────────────────────────┤
│ BB_NUMBER_THREADSPARALLEL_MAKE │ Environment variables to control the │
│ (C,K,E) │ 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). │
└───────────────────────────────────────┴──────────────────────────────────────────────┘
Kas
Part of the kas(1) suite.
Name
kas - a setup tool for bitbake based projects
Options
PositionalArgumentscmd sub command help
Possible choices: build, checkout, dump, for-all-repos, lock, shell, menu
NamedArguments--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
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)See Also
kas-project-config(1), kas-build(1), kas-credentials(1)
Sub-Commands
kasbuild[-h][--skipSTEP][--force-checkout][--update][-k]
[--target TARGET] [-c TASK] [--provenance {true,mode=min,mode=max}]
[config] [extra_bitbake_args ...] Checksoutallnecessaryrepositoriesandbuildsusingbitbakeasspecifiedintheconfigurationfile.kascheckout[-h][--skipSTEP][--force-checkout][--update][config]
Checks out all necessary repositories and sets up the build directory as specified in the
configuration file.
kasdump[-h][--skipSTEP][--force-checkout][--update][--indentINDENT]
[--sort] [--format {yaml,json}] [--resolve-refs] [--resolve-local]
[--resolve-env | --lock]
[config] Expandanddumpthefinalconfigtostdout.Whenresolvingbranches,thisisdonebeforepatchesareapplied.kasfor-all-repos[-h][--skipSTEP][--force-checkout][--update][-E][-k]
[config] command Runsaspecifiedcommandinallcheckedoutrepositories.kaslock[-h][--skipSTEP][--force-checkout][--update][--indentINDENT]
[--sort]
[config] Createandupdatekasprojectlockfiles.kasshell[-h][--skipSTEP][--force-checkout][--update][-E][-k]
[-c COMMAND]
[config] Runashellinthebuildenvironment.kasmenu[-h][kconfig]
Provides a configuration menu and triggers the build of the choices.
Synopsis
kas [-h] [--version] [-l {debug,info,warning,error,critical}]
{build,checkout,dump,for-all-repos,lock,shell,menu} ...
PNG Icons
