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, make_non_interactive, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_check_signatures, 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, make_non_interactive, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_check_signatures, 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

`clean` plugin

This plugin implements the kas {clean,cleansstate,cleanall} commands. In case a configuration file is provided, it will be used to determine the build system and the files managed by kas.

`clean` command

Clean the build artifacts by removing the build artifacts directory.

usage: kas clean [-h] [--dry-run] [--isar] [config]

Positional Arguments

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

Named Arguments

--dry-run

Do not remove anything, just print what would be removed

Default: False

--isar

Use ISAR build directory layout

Default: False

`cleansstate` command

Removes the build artifacts and the empties the sstate cache.

usage: kas cleansstate [-h] [--dry-run] [--isar] [config]

Positional Arguments

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

Named Arguments

--dry-run

Do not remove anything, just print what would be removed

Default: False

--isar

Use ISAR build directory layout

Default: False

`cleanall` command

Removes the build artifacts, empties the sstate cache and the downloads.

usage: kas cleanall [-h] [--dry-run] [--isar] [config]

Positional Arguments

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

Named Arguments

--dry-run

Do not remove anything, just print what would be removed

Default: False

--isar

Use ISAR build directory layout

Default: False

`diff` plugin

This plugin implements the kas diff command.

This plugin compares two kas configurations and outputs the differences. The diff includes both content differences in the configuration files and repository differences if commit IDs or tags have changed.

Additionally, you can use the --format json option to output the diff in JSON format.

Note

The text output of the plugin should not considered to be stable. If stable output is needed, use a machine readable format like json.

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

Positional Arguments

config1: The first config file to be compared.
config2: The second config file to be compared.

Named Arguments

--skip

Possible choices: setup_dir, setup_home, make_non_interactive, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_check_signatures, 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: json, text

Diff output format (default: text)

Default: 'text'

--oneline

Use git oneline output for differing commits.

Default: False

--no-color

Disable colored highlighting of diffs.

Default: False

--commit-only

This will not display the differences in the kas configurations; it will only list commits resulting from different repository revisions.

Default: False

--content-only

This will only display the differences in the kas configurations and will not include repository differences.

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 analyze 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. For details on the locking support, see kas.plugins.lock.

Note

The options to create and update lock files have been moved to the lock plugin.

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
the ordering of the keys is kept unless --sort is used. If you intend to store the flattened configs for comparison, it is recommended to sort the keys.

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

usage: kas dump [-h] [--skip STEP] [--force-checkout] [--update]
                [--indent INDENT] [--sort] [--format {yaml,json}]
                [--resolve-refs] [--resolve-local] [--resolve-env | --lock]
                [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, make_non_interactive, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_check_signatures, 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

--indent

Line indent (# of spaces, default: 2)

Default: 2

--sort

Alphanumerically sort keys in output

Default: False

--format

Possible choices: yaml, json

Output format (default: yaml)

Default: 'yaml'

--resolve-refs

Replace floating refs with exact SHAs. Overrides are removed

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

`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 refspec 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, make_non_interactive, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_check_signatures, 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

`lock` plugin

This plugin implements the kas lock command.

When this command is executed a locking spec is created which only contains the exact commit of each repository. This is used to pin the commit of floating branches and tags, while still keeping an easy update path. The lockfile is created next to the first file on the kas cmdline. For details on the locking support, see kas.includehandler.IncludeHandler.

Note

all referenced repositories are checked out to resolve cross-repo configs
all branches are resolved before patches are applied

Updating lockfiles

When updating lockfiles, kas attempts to update the repository revisions in the lockfile that defines the revision. If a repository is exclusively locked in an external lockfile, this lock is not updated (we cannot modify an external repository). However, if the revision is also defined in a local lockfile, it is updated in the local lockfile.

The algorithm for determining where to pin the revision of a repository is as follows:

Find all repositories that have a floating ref (i.e. no commit). Assign to to-lock list
Iterate over all lockfiles (in include order)
1. for each repository, check if it is locked in the current file
  1. if lock is up to date, remove from to-lock list
  2. else if lockfile is internal, update lockfile, remove from to-lock list
  3. else (repo is locked in external lockfile): mark repo external
Remove all repos with external marks from to-lock list
Add all remaining repos in to-lock list to topmost lockfile, create if needed

Examples

The lockfile is created as kas-project.lock.yml. Call again to regenerate lockfile:

kas lock --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 lock [-h] [--skip STEP] [--force-checkout] [--update]
                [--indent INDENT] [--sort]
                [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, make_non_interactive, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_check_signatures, 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

--indent

Line indent (# of spaces, default: 2)

Default: 2

--sort

Alphanumerically sort keys in output

Default: False

`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'

`purge` plugin

Clears the contents of the build directory, sstate-cache, downloads and the repos managed by kas (including referenced repos in KAS_REPO_REF_DIR, if set). In KAS_WORK_DIR it will remove the default configuration file and the KAS_BUILD_DIR (if present). To preserve the reference repositories, run with --preserve-repo-refs. This command requires a configuration file to locate the managed repos.

Note

Before purging, kas needs to checkout and resolve all repos to locate the repos managed by kas.

usage: kas purge [-h] [--dry-run] [--isar] [--preserve-repo-refs] [config]

Positional Arguments

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

Named Arguments

--dry-run

Do not remove anything, just print what would be removed

Default: False

--isar

Use ISAR build directory layout

Default: False

--preserve-repo-refs

Do not remove the reference repositories

Default: False

`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. The SHELL environment variable is inherited from the calling environment and controls which shell is started.

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, make_non_interactive, init_setup_repos, repo_setup_loop, finish_setup_repos, repos_checkout, repos_check_signatures, 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

clean plugin

clean command

Positional Arguments

Named Arguments

cleansstate command

Positional Arguments

Named Arguments

cleanall command

Positional Arguments

Named Arguments

diff plugin

Positional Arguments

Named Arguments

dump plugin

Positional Arguments

Named Arguments

for-all-repos plugin

Positional Arguments

Named Arguments

lock plugin

Positional Arguments

Named Arguments

menu plugin

Positional Arguments

purge plugin

Positional Arguments

Named Arguments

shell plugin

Positional Arguments

Named Arguments

`build` plugin

`checkout` plugin

`clean` plugin

`clean` command

`cleansstate` command

`cleanall` command

`diff` plugin

`dump` plugin

`for-all-repos` plugin

`lock` plugin

`menu` plugin

`purge` plugin

`shell` plugin