Sub-commands (Plugins)

kas sub-commands are implemented by a series of plugins. Each plugin typically provides a single command.

`build` plugin

This plugin implements the kas build command.

When this command is executed, kas will checkout repositories, setup the build environment and then invoke bitbake to build the targets selected in the chosen config file.

When running with --provenance <true|mode=...> kas will generate an provenance attestation for the build. The attestation will be stored in attestation/kas-build.provenance.json in the build directory. For details about provenance, see the build attestation chapter.

Note

In provenance mode, the command returns with a non-zero exit code in case no artifact is found for at least one entry.

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

Positional Arguments

config: Config file(s), separated by colon. Using .config.yaml in KAS_WORK_DIR if none is specified.
extra_bitbake_args: Extra arguments to pass to bitbake (typically requires separation via ‘–‘)

Named Arguments

--skip

Possible choices: setup_dir, setup_home, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_apply_patches, setup_environ, write_bbconfig

Skip build steps. To skip more than one step, use this argument multiple times.

Default: []

--force-checkout

Always checkout the desired commit/branch/tag of each repository, discarding any local changes

Default: False

--update

Pull new upstream changes to the desired branch even if it is already checked out locally

Default: False

-k, --keep-config-unchanged

Skip steps that change the configuration

--target

Select target to build

-c, --cmd, --task

Select which task should be executed

--provenance

Possible choices: true, mode=min, mode=max

Enable provenance attestation generation

`checkout` plugin

This plugin implements the kas checkout command.

When this command is executed, kas will checkout repositories and set up the build directory as specified in the chosen config file. This command is useful if you need to inspect the configuration or modify any of the checked out layers before starting a build.

For example, to setup the configuration described in the file kas-project.yml you could run:

kas checkout kas-project.yml

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

Positional Arguments

config: Config file(s), separated by colon. Using .config.yaml in KAS_WORK_DIR if none is specified.

Named Arguments

--skip

Possible choices: setup_dir, setup_home, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_apply_patches, setup_environ, write_bbconfig

Skip build steps. To skip more than one step, use this argument multiple times.

Default: []

--force-checkout

Always checkout the desired commit/branch/tag of each repository, discarding any local changes

Default: False

--update

Pull new upstream changes to the desired branch even if it is already checked out locally

Default: False

`dump` plugin

This plugin implements the kas dump command.

When this command is executed in default mode, kas will parse all referenced config files, expand includes and print a flattened yaml version of the configuration to stdout. This config is semantically identical to the input, but does not include any references to other configuration files. The output of this command can be used to further analyse the build configuration.

When running with --lock, a locking spec is created which only contains the exact commit of each repository. This can be used to pin the commit of floating branches and tags, while still keeping an easy update path. When combining with --inplace, a lockfile is created next to the first file on the kas cmdline. For details on the locking support, see kas.includehandler.IncludeHandler.

When running with --resolve-local, VCS tracking information of the root repo (the one with the kas-project.yml) is added to the output. The generated file can be used as single input to kas to reproduce the build environment. If the root repo is not under version control or contains uncommitted changes, a warning is emitted.

Please note:

the dumped config is semantically identical but not bit-by-bit identical
all referenced repositories are checked out to resolve cross-repo configs
all branches are resolved before patches are applied

For example, to get a single config representing the final build config of kas-project.yml:target-override.yml you could run:

kas dump kas-project.yml:target-override.yml > kas-project-expanded.yml

The generated config can be used as input for kas:

kas build kas-project-expanded.yml

Example of the locking mechanism (call again to regenerate lockfile). The lockfile is created as kas-project.lock.yml:

kas dump --lock --inplace --update kas-project.yml

The generated lockfile will automatically be used to pin the revisions:

kas build kas-project.yml

Note, that the lockfiles should be checked-in into the VCS.

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

Positional Arguments

config: Config file(s), separated by colon. Using .config.yaml in KAS_WORK_DIR if none is specified.

Named Arguments

--skip

Possible choices: setup_dir, setup_home, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_apply_patches, setup_environ, write_bbconfig

Skip build steps. To skip more than one step, use this argument multiple times.

Default: []

--force-checkout

Always checkout the desired commit/branch/tag of each repository, discarding any local changes

Default: False

--update

Pull new upstream changes to the desired branch even if it is already checked out locally

Default: False

--format

Possible choices: yaml, json

Output format (default: yaml)

Default: “yaml”

--indent

Line indent (# of spaces, default: 4)

Default: 4

--resolve-refs

Replace floating refs with exact SHAs

Default: False

--resolve-local

Add tracking information of root repo

Default: False

--resolve-env

Set env defaults to captured env value

Default: False

--lock

Create lockfile with exact SHAs

Default: False

-i, --inplace

Update lockfile in-place (requires –lock)

Default: False

`for-all-repos` plugin

This plugin implements the kas for-all-repos command.

When this command is executed, kas will checkout the repositories listed in the chosen config file and then execute a specified command in each repository. It can be used to query the repository status, automate actions such as archiving the layers used in a build or to execute any other required commands.

For example, to print the commit hashes used by each repository used in the file kas-project.yml (assuming they are all git repositories) you could run:

kas for-all-repos kas-project.yml 'git rev-parse HEAD'

The environment for executing the command in each repository is extended to include the following variables:

KAS_REPO_NAME: The name of the current repository determined by either the name property or by the key used for this repo in the config file.

KAS_REPO_PATH: The path of the local directory where this repository is checked out, relative to the directory where kas is executed.

KAS_REPO_URL: The URL from which this repository was cloned, or an empty string if no remote URL was given in the config file.

KAS_REPO_COMMIT: The commit ID which was checked out for this repository, or an empty string if no commit was given in the config file.

KAS_REPO_BRANCH: The branch which was checked out for this repository, or an empty string if no branch was given in the config file.

KAS_REPO_TAG: The tag which was checked out for this repository, or an empty string if no tag was given in the config file.

KAS_REPO_REFSPEC: The refspec which was checked out for this repository, or an empty string if no refspec was given in the config file. This variable is obsolete and will be removed when support for respec keys is removed as well. Migrate your repos to commit/branch and use the related variables instead.

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

Positional Arguments

config: Config file(s), separated by colon. Using .config.yaml in KAS_WORK_DIR if none is specified.
command: Command to be executed as a string.

Named Arguments

--skip

Possible choices: setup_dir, setup_home, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_apply_patches, setup_environ, write_bbconfig

Skip build steps. To skip more than one step, use this argument multiple times.

Default: []

--force-checkout

Always checkout the desired commit/branch/tag of each repository, discarding any local changes

Default: False

--update

Pull new upstream changes to the desired branch even if it is already checked out locally

Default: False

-E, --preserve-env

Keep current user environment block

Default: False

-k, --keep-config-unchanged

Skip steps that change the configuration

`menu` plugin

This plugin implements the kas menu command.

When this command is executed, kas will open a configuration menu as described by a Kconfig file. It processes any pre-existing configuration file with saved settings, stores the final selections and invokes the build plugin if requested by the user.

To make use of this plugin, a Kconfig file has to be provided. The menu can define these types of configuration variables that the plugin will translate into a kas configuration:

kas configuration files that will be included when building the generated configuration. Those are picked up from kconfig string variables that have the name prefix KAS_INCLUDE_.

bitbake targets that shall be built via the generated configuration. Those are picked up from kconfig string variables that have the name prefix KAS_TARGET_.

The build_system that will used. The static kconfig string variable KAS_BUILD_SYSTEM defines this value which must be openembedded, oe or isar is set.

bitbake configuration variables that will be added to the local_conf_header section of the generated configuration. All other active kconfig string, integer or hex variables are treated as such.

See https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html for a complete documentation of the Kconfig language.

The menu plugin writes the selected configuration to a .config.yaml file in the kas work directory and also reads previous selection from such a file if it exists. The .config.yaml both contains the selected configuration in the menu_configuration key and also the effective settings that can be used to invoke kas build or other kas commands.

usage: kas menu [-h] [kconfig]

Positional Arguments

kconfig

Kconfig file

Default: “Kconfig”

`shell` plugin

This plugin implements the kas shell command.

When this command is executed, kas will checkout repositories, setup the build environment and then start a shell in the build environment. This can be used to manually run bitbake with custom command line options or to execute other commands such as runqemu.

For example, to start a shell in the build environment for the file kas-project.yml you could run:

kas shell kas-project.yml

Or to invoke qemu to test an image which has been built:

kas shell kas-project.yml -c 'runqemu'

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

Positional Arguments

config: Config file(s), separated by colon. Using .config.yaml in KAS_WORK_DIR if none is specified.

Named Arguments

--skip

Possible choices: setup_dir, setup_home, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_apply_patches, setup_environ, write_bbconfig

Skip build steps. To skip more than one step, use this argument multiple times.

Default: []

--force-checkout

Always checkout the desired commit/branch/tag of each repository, discarding any local changes

Default: False

--update

Pull new upstream changes to the desired branch even if it is already checked out locally

Default: False

-E, --preserve-env

Keep current user environment block

Default: False

-k, --keep-config-unchanged

Skip steps that change the configuration

-c, --command

Run command

Default: “”

Sub-commands (Plugins)

build plugin

Positional Arguments

Named Arguments

checkout plugin

Positional Arguments

Named Arguments

dump plugin

Positional Arguments

Named Arguments

for-all-repos plugin

Positional Arguments

Named Arguments

menu plugin

Positional Arguments

shell plugin

Positional Arguments

Named Arguments

`build` plugin

`checkout` plugin

`dump` plugin

`for-all-repos` plugin

`menu` plugin

`shell` plugin