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. 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
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] [--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, 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
- --indent
Line indent (# of spaces, default: 4)
Default:
4
- --format
Possible choices: yaml, json
Output format (default: yaml)
Default:
'yaml'
- --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
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 wherekas
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
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
.
Please note:
all referenced repositories are checked out to resolve cross-repo configs
all branches are resolved before patches are applied
Example (call again to regenerate lockfile).
The lockfile is created as kas-project.lock.yml
:
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]
[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
- --indent
Line indent (# of spaces, default: 4)
Default:
4
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:
''