Provided by: kas_4.0-1_all 
NAME
kas - kas Documentation
INTRODUCTION
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
USER GUIDE
Dependencies & installation
This project depends on
• Python 3
• distro Python 3 package
• jsonschema Python 3 package
• PyYAML Python 3 package (optional, for yaml file support)
• kconfiglib Python 3 package (optional, for menu plugin)
• NEWT Python 3 distro package (optional, for menu plugin)
To install kas into your python site-package repository, run:
$ sudo pip3 install .
Usage
There are (at least) four options for using kas:
• Install it locally via pip to get the kas command.
• Use the container image locally. In this case, download the kas-container script from
the kas repository and use it in place of the kas command. The script version
corresponds to the kas tool and the kas image version.
• Use the container image in CI. Specify ghcr.io/siemens/kas/kas[-isar][:<x.y>] in your CI
script that requests a container image as runtime environment. See
https://github.com/orgs/siemens/packages/container/kas%2Fkas/versions and
https://github.com/orgs/siemens/packages/container/kas%2Fkas-isar/versions for all
available images.
• Use the run-kas wrapper from this directory. In this case, replace kas in the examples
below with path/to/run-kas.
Start build:
$ kas build /path/to/kas-project.yml
Alternatively, experienced bitbake users can invoke usual bitbake steps manually, e.g.:
$ kas shell /path/to/kas-project.yml -c 'bitbake dosfsutils-native'
kas will place downloads and build artifacts under the current directory when being
invoked. You can specify a different location via the environment variable KAS_WORK_DIR.
Use Cases
1. Initial build/setup:
$ mkdir $PROJECT_DIR
$ cd $PROJECT_DIR
$ git clone $PROJECT_URL meta-project
$ kas build meta-project/kas-project.yml
2. Update/rebuild:
$ cd $PROJECT_DIR/meta-project
$ git pull
$ kas build kas-project.yml
3. Interactive configuration:
$ cd $PROJECT_DIR/meta-project
$ kas menu
$ kas build # optional, if not triggered via kas menu
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.
For example, to build the configuration described in the file kas-project.yml you could
run:
kas build kas-project.yml
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
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, 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.
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.
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_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.
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.
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'
Project Configuration
Currently, JSON and YAML are supported as the base file formats. Since YAML is arguably
easier to read, this documentation focuses on the YAML format.
# Every file needs to contain a header, that provides kas with information
# about the context of this file.
header:
# The `version` entry in the header describes for which configuration
# format version this file was created for. It is used by kas to figure
# out if it is compatible with this file. The version is an integer that
# is increased on every format change.
version: x
# The machine as it is written into the `local.conf` of bitbake.
machine: qemux86-64
# The distro name as it is written into the `local.conf` of bitbake.
distro: poky
repos:
# This entry includes the repository where the config file is located
# to the bblayers.conf:
meta-custom:
# Here we include a list of layers from the poky repository to the
# bblayers.conf:
poky:
url: "https://git.yoctoproject.org/git/poky"
commit: 89e6c98d92887913cadf06b2adb97f26cde4849b
layers:
meta:
meta-poky:
meta-yocto-bsp:
A minimal input file consists out of the header, machine, distro, and repos.
Additionally, you can add bblayers_conf_header and local_conf_header which are strings
that are added to the head of the respective files (bblayers.conf or local.conf):
bblayers_conf_header:
meta-custom: |
POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
local_conf_header:
meta-custom: |
PATCHRESOLVE = "noop"
CONF_VERSION = "1"
IMAGE_FSTYPES = "tar"
meta-custom in these examples should be a unique name for this configuration entries.
We recommend that this unique name is the same as the name of the containing
repository/layer to ease cross-project referencing.
In given examples we assume that your configuration file is part of a meta-custom
repository/layer. This way it is possible to overwrite or append entries in files that
include this configuration by naming an entry the same (overwriting) or using an unused
name (appending).
Including in-tree configuration files
It's currently possible to include kas configuration files from the same repository/layer
like this:
header:
version: x
includes:
- base.yml
- bsp.yml
- product.yml
The paths to the files in the include list are either absolute, if they start with a /, or
relative.
If the path is relative and the configuration file is inside a repository, then path is
relative to the repositories base directory. If the configuration file is not in a
repository, then the path is relative to the parent directory of the file.
Including configuration files from other repos
It's also possible to include configuration files from other repos like this:
header:
version: x
includes:
- repo: poky
file: kas-poky.yml
- repo: meta-bsp-collection
file: hw1/kas-hw-bsp1.yml
- repo: meta-custom
file: products/product.yml
repos:
meta-custom:
meta-bsp-collection:
url: "https://www.example.com/git/meta-bsp-collection"
commit: 3f786850e387550fdab836ed7e6dc881de23001b
layers:
# Additional to the layers that are added from this repository
# in the hw1/kas-hw-bsp1.yml, we add here an additional bsp
# meta layer:
meta-custom-bsp:
poky:
url: "https://git.yoctoproject.org/git/poky"
commit: 89e6c98d92887913cadf06b2adb97f26cde4849b
layers:
# If `kas-poky.yml` adds the `meta-yocto-bsp` layer and we
# do not want it in our bblayers for this project, we can
# overwrite it by setting:
meta-yocto-bsp: excluded
The files are addressed relative to the git repository path.
The include mechanism collects and merges the content from top to bottom and depth first.
That means that settings in one include file are overwritten by settings in a latter
include file and entries from the last include file can be overwritten by the current
file. While merging all the dictionaries are merged recursively while preserving the order
in which the entries are added to the dictionary. This means that local_conf_header
entries are added to the local.conf file in the same order in which they are defined in
the different include files. Note that the order of the configuration file entries is not
preserved within one include file, because the parser creates normal unordered
dictionaries.
Including configuration files via the command line
When specifying the kas configuration file on the command line, additional configurations
can be included ad-hoc:
$ kas build kas-base.yml:debug-image.yml:board.yml
This is equivalent to static inclusion from some kas-combined.yml like this:
header:
version: x
includes:
- kas-base.yml
- debug.image.yml
- board.yml
Command line inclusion allows to create configurations on-demand, without the need to
write a kas configuration file for each possible combination.
Note that all configuration files combined via the command line either have to come from
the same repository or have to live outside of any versioning control. kas will refuse
any other combination in order to avoid complications and configuration flaws that can
easily emerge from them.
Working with lockfiles
KAS supports the use of lockfiles to pinpoint repositories to exact commit ID (e.g. SHA-1
refs for git). A lockfile hereby only overrides the commit ID defined in a kas file. When
performing the checkout operation (or any other operation that performs a checkout), kas
checks if a file named <filename>.lock.<ext> is found next to the first file stated on the
kas cmdline. If this is found, kas appends this filename to the kas cmdline and performs
the requested operation.
The following example shows this mechanism for a file kas/kas-isar.yml and its
corresponding lockfile kas/kas-isar.lock.yml.
kas/kas-isar.yml:
# [...]
repos:
isar:
url: https://github.com/ilbers/isar.git
branch: next
kas/kas-isar.lock.yml:
header:
version: 14
overrides:
repos:
isar:
commit: 0336610df8bb0adce76ef8c5a921c758efed9f45
The dump plugin provides helpers to simplify the creation and update of lockfiles. For
details, see the plugins documentation: kas.plugins.dump.
Configuration reference
header: dict [required]
The header of every kas configuration file. It contains information about the
context of the file.
version: integer [required]
Lets kas check if it is compatible with this file. See the configuration
format changelog for the format history and the latest available version.
includes: list [optional]
A list of configuration files this current file is based on. They are
merged in order they are stated. So a latter one could overwrite settings
from previous files. The current file can overwrite settings from every
included file. An item in this list can have one of two types:
item: string
The path to a kas configuration file, relative to the repository
root of the current file.
item: dict
If files from other repositories should be included, choose this
representation.
repo: string [required]
The id of the repository where the file is located. The
repo needs to be defined in the repos dictionary as
<repo-id>.
file: string [required]
The path to the file, relative to the root of the specified
repository.
build_system: string [optional]
Defines the bitbake-based build system. Known build systems are openembedded (or
oe) and isar. If set, this restricts the search of kas for the init script in
the configured repositories to oe-init-build-env or isar-init-build-env,
respectively. If kas-container finds this property in the top-level kas
configuration file (includes are not evaluated), it will automatically select
the required container image and invocation mode.
defaults: dict [optional]
This key can be used to set default values for various properties. This may
help you to avoid repeating the same property assignment in multiple places if,
for example, you wish to use the same branch for all repositories.
repos: dict [optional]
This key can contain default values for some repository properties. If a
default value is set for a repository property it may still be overridden
by setting the same property to a different value in a given repository.
branch: string [optional]
Sets the default branch property applied to all repositories that
do not override this.
patches: dict [optional]
This key can contain default values for some repository patch
properties. If a default value is set for a patch property it may
still be overridden by setting the same property to a different
value in a given patch.
repo: string [optional]
Sets the default repo property applied to all repository
patches that do not override this.
machine: string [optional]
Contains the value of the MACHINE variable that is written into the local.conf.
Can be overwritten by the KAS_MACHINE environment variable and defaults to
qemux86-64.
distro: string [optional]
Contains the value of the DISTRO variable that is written into the local.conf.
Can be overwritten by the KAS_DISTRO environment variable and defaults to poky.
target: string [optional] or list [optional]
Contains the target or a list of targets to build by bitbake. Can be overwritten
by the KAS_TARGET environment variable and defaults to core-image-minimal. Space
is used as a delimiter if multiple targets should be specified via the
environment variable.
env: dict [optional]
Contains environment variable names with either default values or None. These
variables are made available to bitbake via BB_ENV_EXTRAWHITE and can be
overwritten by the variables of the environment in which kas is started. Either
a string or nothing (None) can be assigned as value. The former one serves as a
default value whereas the latter one will lead to add the variable only to
BB_ENV_EXTRAWHITE and not to the environment where kas is started.
task: string [optional]
Contains the task to build by bitbake. Can be overwritten by the KAS_TASK
environment variable and defaults to build.
repos: dict [optional]
Contains the definitions of all available repos and layers.
<repo-id>: dict [optional]
Contains the definition of a repository and the layers, that should be
part of the build. If the value is None, the repository, where the
current configuration file is located is defined as <repo-id> and added
as a layer to the build. It is recommended that the <repo-id> is related
to the containing repository/layer to ease cross-project referencing.
name: string [optional]
Defines under which name the repository is stored. If its missing
the <repo-id> will be used.
url: string [optional]
The url of the repository. If this is missing, no version control
operations are performed.
type: string [optional]
The type of version control repository. The default value is git
and hg is also supported.
commit: string [optional]
The commit ID (branch names, no symbolic refs, no tags) that
should be used. If url was specified but no commit and no branch,
the revision you get depends on the defaults of the version
control system used.
branch: string [optional]
The upstream branch that should be tracked. If no commit was
specified, the head of the upstream is checked out.
path: string [optional]
The path where the repository is stored. If the url and path is
missing, the repository where the current configuration file is
located is defined. If the url is missing and the path defined,
this entry references the directory the path points to. If the
url as well as the path is defined, the path is used to overwrite
the checkout directory, that defaults to kas_work_dir + repo.name.
In case of a relative path name kas_work_dir is prepended.
layers: dict [optional]
Contains the layers from this repository that should be added to
the bblayers.conf. If this is missing or None or an empty
dictionary, the path to the repo itself is added as a layer.
Additionally, . is a valid value if the repo itself should be
added as a layer. This allows combinations:
repos:
meta-foo:
url: https://github.com/bar/meta-foo.git
path: layers/meta-foo
branch: master
layers:
.:
contrib:
This adds both layers/meta-foo and layers/meta-foo/contrib from
the meta-foo repository to bblayers.conf.
<layer-path>: enum [optional]
Adds the layer with <layer-path> that is relative to the
repository root directory, to the bblayers.conf if the
value of this entry is not in this list: ['disabled',
'excluded', 'n', 'no', '0', 'false']. This way it is
possible to overwrite the inclusion of a layer in latter
loaded configuration files.
patches: dict [optional]
Contains the patches that should be applied to this repo before it
is used.
<patches-id>: dict [optional]
One entry in patches with its specific and unique id. All
available patch entries are applied in the order of their
sorted <patches-id>.
repo: string [required]
The identifier of the repo where the path of this
entry is relative to.
path: string [required]
The path to one patch file or a quilt formatted
patchset directory.
overrides: dict [optional]
This object provides a mechanism to override kas configuration items without
defining them. By that, only items that already exist are overridden. Note, that
all entries below this key are reserved for auto-generation using kas plugins.
Do not manually add entries.
repos: dict [optional]
Mapps to the top-level repos entry.
<repo-id>: dict [optional]
Mapps to the <repo-id> entry.
commit: string [optional]
Pinned commit ID which overrides the commit of the
corresponding repo.
bblayers_conf_header: dict [optional]
This contains strings that should be added to the bblayers.conf before any
layers are included.
<bblayers-conf-id>: string [optional]
A string that is added to the bblayers.conf. The entry id
(<bblayers-conf-id>) should be unique if lines should be added and can be
the same from another included file, if this entry should be overwritten.
The lines are added to bblayers.conf in alphabetic order of
<bblayers-conf-id> to ensure deterministic generation of config files.
local_conf_header: dict [optional]
This contains strings that should be added to the local.conf.
<local-conf-id>: string [optional]
A string that is added to the local.conf. It operates in the same way as
the bblayers_conf_header entry.
menu_configuration:: dict [optional]
This contains user choices for a Kconfig menu of a project. Each variable
corresponds to a Kconfig configuration variable and can be of the types string,
boolean or integer. The content of this key is typically maintained by the kas
menu plugin in a .config.yaml file.
_source_dir:: string [optional]
This entry is auto-generated by the menu plugin and provides the path to the top
repo at time of invoking the plugin. It must not be set manually and might only
be defined in the top-level .config.yaml file.
_source_dir_host:: string [optional]
This entry is auto-generated by the menu plugin when invoking kas via the
kas-container script. It provides the absolute path to the top repo outside of
the container (on the host). This value is only evaluated by the kas-container
script. It must not be set manually and might only be defined in the top-level
.config.yaml file.
COMMAND LINE USAGE
kas - setup tool for bitbake based project
usage: kas [-h] [--version] [-d] [-l {debug,info,warning,error,critical}]
{build,checkout,dump,for-all-repos,shell,menu} ...
Positional Arguments
cmd Possible choices: build, checkout, dump, for-all-repos, shell, menu
sub command help
Named Arguments
--version
show program's version number and exit
-d, --debug
Enable debug logging (deprecated, use --log-level debug).
-l, --log-level
Possible choices: debug, info, warning, error, critical
Set log level (default: info)
Default: "info"
Sub-commands
build
Checks out all necessary repositories and builds using bitbake as specified in the
configuration file.
kas build [-h] [--skip SKIP] [--force-checkout] [--update] [--target TARGET]
[-c TASK]
[config] [extra_bitbake_args ...]
Positional Arguments
config Config file, 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 Skip build steps
Default: []
--force-checkout
Always checkout the desired commit/branch 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
--target
Select target to build
-c, --cmd, --task
Select which task should be executed
checkout
Checks out all necessary repositories and sets up the build directory as specified in the
configuration file.
kas checkout [-h] [--skip SKIP] [--force-checkout] [--update] [config]
Positional Arguments
config Config file, using .config.yaml in KAS_WORK_DIR if none is specified
Named Arguments
--skip Skip build steps
Default: []
--force-checkout
Always checkout the desired commit/branch 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
Expand and dump the final config to stdout. When resolving branches, this is done before
patches are applied.
kas dump [-h] [--skip SKIP] [--force-checkout] [--update]
[--format {yaml,json}] [--indent INDENT] [--resolve-refs]
[--resolve-env | --lock] [-i]
[config]
Positional Arguments
config Config file, using .config.yaml in KAS_WORK_DIR if none is specified
Named Arguments
--skip Skip build steps
Default: []
--force-checkout
Always checkout the desired commit/branch 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-env
Set env defaults to captured env value
Default: False
--lock Create lockfile with exact SHAs
Default: False
-i, --inplace
Update lockfile in-place (reqires --lock)
Default: False
for-all-repos
Runs a specified command in all checked out repositories.
kas for-all-repos [-h] [--skip SKIP] [--force-checkout] [--update] [-E]
[config] command
Positional Arguments
config Config file, using .config.yaml in KAS_WORK_DIR if none is specified
command
Command to be executed as a string.
Named Arguments
--skip Skip build steps
Default: []
--force-checkout
Always checkout the desired commit/branch 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
shell
Run a shell in the build environment.
kas shell [-h] [--skip SKIP] [--force-checkout] [--update] [-E] [-k]
[-c COMMAND]
[config]
Positional Arguments
config Config file, using .config.yaml in KAS_WORK_DIR if none is specified
Named Arguments
--skip Skip build steps
Default: []
--force-checkout
Always checkout the desired commit/branch 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
Default: False
-c, --command
Run command
Default: ""
menu
Provides a configuration menu and triggers the build of the choices.
kas menu [-h] [kconfig]
Positional Arguments
kconfig
Kconfig file
Default: "Kconfig"
Environment variables
┌─────────────────────────────────┬──────────────────────────────────────────────┐
│Environment variables │ Description │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│KAS_WORK_DIR │ The path of the kas work │
│ │ directory, current work │
│ │ directory is the default. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│KAS_BUILD_DIR │ The path build directory, │
│ │ ${KAS_WORK_DIR}/build is the │
│ │ default. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│KAS_REPO_REF_DIR │ 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. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│KAS_DISTRO KAS_MACHINE │ This overwrites the respective setting in │
│KAS_TARGET KAS_TASK │ the configuration file. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│KAS_PREMIRRORS │ Specifies alternatives for repo URLs. Just │
│DISTRO_APT_PREMIRRORS │ 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/" │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│SSH_PRIVATE_KEY │ 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 │ 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 │ SSH authentication socket. Used for cloning │
│ │ over SSH (alternative to SSH_PRIVATE_KEY or │
│ │ SSH_PRIVATE_KEY_FILE). │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│DL_DIR SSTATE_DIR TMPDIR │ Environment variables that are transferred │
│ │ to the bitbake environment. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│http_proxy https_proxy ftp_proxy │ These variables define the proxy │
│no_proxy │ configuration bitbake should use. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│GIT_PROXY_COMMAND NO_PROXY │ Set proxy for native git fetches. NO_PROXY │
│ │ is evaluated by OpenEmbedded's oe-git-proxy │
│ │ script. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│SHELL │ The shell to start when using the shell │
│ │ plugin. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│TERM │ The terminal options used in the shell │
│ │ plugin. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│AWS_CONFIG_FILE │ Path to the awscli configuration and │
│AWS_SHARED_CREDENTIALS_FILE │ credentials file that are copied to the kas │
│ │ home dir. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│GIT_CREDENTIAL_HELPER │ Allows to set and configure the git │
│GIT_CREDENTIAL_USEHTTPPATH │ credential helper in the .gitconfig of the │
│ │ kas user. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│NETRC_FILE │ Path to a .netrc file which will be copied │
│ │ to the kas home dir as .netrc. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│CI_SERVER_HOST CI_JOB_TOKEN │ 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. │
├─────────────────────────────────┼──────────────────────────────────────────────┤
│BB_NUMBER_THREADS PARALLEL_MAKE │ Environment variables to control the │
│ │ concurrency │
└─────────────────────────────────┴──────────────────────────────────────────────┘
DEVELOPER GUIDE
Deploy for development
This project uses pip to manage the package. If you want to work on the project yourself
you can create the necessary links via:
$ pip3 install --user -e .
That will install a backlink ~/.local/bin/kas to this project. Now you are able to call it
from anywhere.
Docker image build
For the Yocto/OE build image, just run:
$ docker build -t <kas_image_name> .
For the Yocto/OE build image, use:
$ docker build --target kas-isar -t <kas-isar_image_name> .
When you need a proxy to access the internet, add:
--build-arg http_proxy=<http_proxy> --build-arg https_proxy=<https_proxy>
--build-arg ftp_proxy=<ftp_proxy> --build-arg no_proxy=<no_proxy>
to the call.
Measure code coverage
To measure the code coverage of the unit tests, the pytest-cov package is required. On
Debian systems, this is provided in python3-pytest-cov. Once installed, run:
$ python3 -m pytest --cov --cov-report html
The coverage in HTML format can then be found in htmlcov.
Community Resources
Project home:
• https://github.com/siemens/kas
Source code:
• https://github.com/siemens/kas.git
• git@github.com:siemens/kas.git
Documentation:
• https://kas.readthedocs.org
Mailing list:
• kas-devel@googlegroups.com
• Subscription:
• kas-devel+subscribe@googlegroups.com
• https://groups.google.com/forum/#!forum/kas-devel/join
• Archives
• https://groups.google.com/forum/#!forum/kas-devel
• https://www.mail-archive.com/kas-devel@googlegroups.com/
Class reference documentation
kas.kas Module
This module is the main entry point for kas, setup tool for bitbake based projects. In
case of user errors (e.g. invalid configuration, repo fetch failure) KAS exits with error
code 2, while exiting with 1 for internal errors. For details on error handling, see
kas.kasusererror.
kas.kas.create_logger()
Setup the logging environment
kas.kas.interruption()
Ignore SIGINT/SIGTERM in kas, let them be handled by our sub-processes
kas.kas.kas(argv)
The actual main entry point of kas.
kas.kas.kas_get_argparser()
Creates an argparser for kas with all plugins.
kas.kas.main()
The main function that operates as a wrapper around kas.
kas.libkas Module
This module contains the core implementation of kas.
exception kas.libkas.EnvNotValidError
The caller environment is not suited for the requested operation
exception kas.libkas.InitBuildEnvError
Error related to the OE / ISAR environment setup scripts
class kas.libkas.LogOutput(live)
Handles the log output of executed applications
log_stderr(line)
This method is called when a line is received over stderr.
log_stdout(line)
This method is called when a line is received over stdout.
exception kas.libkas.TaskExecError(command, ret_code)
Similar to kas.kasusererror.CommandExecError but for kas internal tasks
kas.libkas.find_program(paths, name)
Find a file within the paths array and returns its path.
kas.libkas.get_build_environ(build_system)
Creates the build environment variables.
kas.libkas.repos_apply_patches(repos)
Applies the patches to the repositories.
kas.libkas.repos_fetch(repos)
Fetches the list of repositories to the kas_work_dir.
kas.libkas.run_cmd(cmd, cwd, env=None, fail=True, liveupdate=True)
Runs a command synchronously.
async kas.libkas.run_cmd_async(cmd, cwd, env=None, fail=True, liveupdate=True)
Run a command asynchronously.
kas.libkas.ssh_add_key(env, key)
Adds an ssh key to the ssh-agent
kas.libkas.ssh_add_key_file(env, key_path)
Adds an ssh key file to the ssh-agent
kas.libkas.ssh_cleanup_agent()
Removes the identities and stops the ssh-agent instance
kas.libkas.ssh_no_host_key_check()
Disables ssh host key check
kas.libkas.ssh_setup_agent(envkeys=None)
Starts the ssh-agent
kas.libcmds Module
This module contains common commands used by kas plugins.
class kas.libcmds.CleanupSSHAgent
Removes all the identities and stops the ssh-agent instance.
execute(ctx)
This method executes the command.
class kas.libcmds.Command
An abstract class that defines the interface of a command.
execute(ctx)
This method executes the command.
class kas.libcmds.FinishSetupRepos
Finalizes the repo setup loop
execute(ctx)
This method executes the command.
class kas.libcmds.InitSetupRepos
Prepares setting up repos including the include logic
execute(ctx)
This method executes the command.
class kas.libcmds.Loop(name)
A class that defines a set of commands as a loop.
add(command)
Appends a command to the loop.
execute(ctx)
Executes the loop.
class kas.libcmds.Macro(use_common_setup=True, use_common_cleanup=True)
Contains commands and provides method to run them.
add(command)
Appends commands to the command list.
run(ctx, skip=None)
Runs a command from the command list with respect to the configuration.
class kas.libcmds.ReposApplyPatches
Applies the patches defined in the configuration to the repositories.
execute(ctx)
This method executes the command.
class kas.libcmds.ReposCheckout
Ensures that the right revision of each repo is checked out.
execute(ctx)
This method executes the command.
class kas.libcmds.ReposFetch
Fetches repositories defined in the configuration
execute(ctx)
This method executes the command.
class kas.libcmds.SetupDir
Creates the build directory.
execute(ctx)
This method executes the command.
class kas.libcmds.SetupEnviron
Sets up the kas environment.
execute(ctx)
This method executes the command.
class kas.libcmds.SetupHome
Sets up the home directory of kas.
execute(ctx)
This method executes the command.
class kas.libcmds.SetupReposStep
Single step of the checkout repos loop
execute(ctx)
This method executes the command.
class kas.libcmds.SetupSSHAgent
Sets up the ssh agent configuration.
execute(ctx)
This method executes the command.
class kas.libcmds.WriteBBConfig
Writes bitbake configuration files into the build directory.
execute(ctx)
This method executes the command.
kas.config Module
This module contains the implementation of the kas configuration.
class kas.config.Config(ctx, filename, target=None, task=None)
Implements the kas configuration based on config files.
find_missing_repos(repo_paths={})
Returns repos that are in config but not on disk
get_bblayers_conf_header()
Returns the bblayers.conf header
get_bitbake_targets()
Returns a list of bitbake targets
get_bitbake_task()
Returns the bitbake task
get_build_system()
Returns the pre-selected build system
get_config()
Returns the config dict.
get_distro()
Returns the distro
get_environment()
Returns the configured environment variables from the configuration file
with possible overwritten values from the environment.
get_local_conf_header()
Returns the local.conf header
get_machine()
Returns the machine
get_multiconfig()
Returns the multiconfig array as bitbake string
get_repo(name)
Returns a Repo instance for the configuration with the key name.
get_repos()
Returns the list of repos.
get_repos_config()
Returns the repository configuration
kas.repos Module
This module contains the Repo class.
class kas.repos.GitRepo(name, url, path, commit, branch, refspec, layers, patches,
disable_operations)
Provides the git functionality for a Repo.
class kas.repos.MercurialRepo(name, url, path, commit, branch, refspec, layers, patches,
disable_operations)
Provides the hg functionality for a Repo.
exception kas.repos.PatchApplyError
The provided patch file could not be applied
exception kas.repos.PatchFileNotFound
The requested patch file was not found
exception kas.repos.PatchMappingError
The requested patch can not be related to a repo
class kas.repos.Repo(name, url, path, commit, branch, refspec, layers, patches,
disable_operations)
Represents a repository in the kas configuration.
static factory(name, repo_config, repo_defaults, repo_fallback_path,
repo_overrides={})
Returns a Repo instance depending on params.
static get_root_path(path, fallback=True)
Checks if path is under version control and returns its root path.
class kas.repos.RepoImpl(name, url, path, commit, branch, refspec, layers, patches,
disable_operations)
Provides a generic implementation for a Repo.
async apply_patches_async()
Applies patches to a repository asynchronously.
checkout()
Checks out the correct revision of the repo.
async fetch_async()
Starts asynchronous repository fetch.
exception kas.repos.RepoRefError
The requested repo reference is invalid, missing or could not be found
exception kas.repos.UnsupportedRepoTypeError
The requested repo type is unsupported / not implemented
kas.includehandler Module
This module implements how includes of configuration files are handled in kas.
exception kas.includehandler.IncludeException
Class for exceptions that appear in the include mechanism.
class kas.includehandler.IncludeHandler(top_files, top_repo_path, use_lock=True)
Implements a handler where every configuration file should contain a dictionary as
the base type with and 'includes' key containing a list of includes.
The includes can be specified in two ways: as a string containing the path,
relative to the repository root from the current file, or as a dictionary. The
dictionary must have a 'file' key containing the path to the include file and a
'repo' key containing the key of the repository. The path is interpreted relative
to the repository root path.
The includes are read and merged from the deepest level upwards.
In case ignore_lock is false, kas checks if a file <file>.lock.<ext> exists next to
the first entry in top_files. This filename is then appended to the list of
top_files.
get_config(repos=None)
Parameters:
repos -- A dictionary that maps repo names to directory paths
Returns:
(config, repos)
config -- A dictionary containing the configuration repos -- A
list of missing repo names that are needed
to create a complete configuration
exception kas.includehandler.LoadConfigException(message, filename)
Class for exceptions that appear while loading a configuration file.
kas.includehandler.load_config(filename)
Load the configuration file and test if version is supported.
kas.kasusererror Module
This module provides a common base class for all exceptions which are related to user or
configuration errors. These exceptions should be caught and reported to the user using a
meaningful message instead of a stacktrace.
When handling errors in KAS, never return directly using sys.exit, but instead throw an
exception derived from KasUserError (for user errors), or one derived from Exception for
internal errors. These are then handled centrally, mapped to correct return codes and
pretty printed.
exception kas.kasusererror.ArgsCombinationError(message)
Invalid combination of CLI arguments provided
exception kas.kasusererror.CommandExecError(command, ret_code, forward_ret_code=False)
Failure in execution of a shell command. The forward_error_code parameter can be
used to request the receiver of the exception to sys.exit with that code instead of
a generic one. Only use this in special cases, where the return code can actually
be related to a single shell command.
exception kas.kasusererror.KasUserError
User or input error. Derive all user error exceptions from this class.
kas.plugins Module
This module contains and manages kas plugins
kas.plugins.all()
Get a list of all loaded kas plugin classes
kas.plugins.get(name)
Lookup a kas plugin class by name
kas.plugins.load()
Import all kas plugins
kas.plugins.register_plugins(mod)
Register all kas plugins found in a module
CONFIGURATION FORMAT CHANGES
Version 1 (Alias '0.10')
Added
• Include mechanism
• Version check
Version 2
Changed
• Configuration file versions are now integers
Fixed
• Including files from repos that are not defined in the current file
Version 3
Added
• Task key that allows to specify which task to run (bitbake -c)
Version 4
Added
• Target key now allows to be a list of target names
Version 5
Changed behavior
• Using multiconfig:* targets adds appropriate BBMULTICONFIG entries to the local.conf
automatically.
Version 6
Added
• env key now allows to pass custom environment variables to the bitbake build process.
Version 7
Added
• type property to repos to be able to express which version control system to use.
Version 8
Added
• patches property to repos to be able to apply additional patches to the repo.
Version 9
Added
• defaults key can now be used to set a default value for the repository property refspec
and the repository patch property repo. These default values will be used if the
appropriate properties are not defined for a given repository or patch.
Version 10
Added
• build_system property to pre-select OE or Isar.
Version 11
Changed behavior
• String item includes are now using repo-relative paths. File-relative is still supported
by issues a deprecation warning.
• bblayers.conf is generated with BBPATH and BBFILES preset to common defaults. Those can
still be overwritten via bblayers_conf_headers.
Added
• menu_configuration key stores the selections done via kas menu in a configuration file.
It is only evaluated by that plugin.
Version 12
Added
• For repositories, url and path can now be overridden with a null-value to switch between
version-controlled repositories and unversioned local folders.
Version 13
Added
• Variables used in the env section can now be assigned 'None' as value. In this case the
variables are only exported to the bb env whitelist.
Version 14
Added
• The keys commit and branch are introduced as replacement of refspec in repos and
defaults. refspec is now deprecated and will eventually be removed.
• The overrides top-level entry can be used to pin floating repo branches.
• _source_dir top-level entry is auto-generated when using the menu plugin and provides
the path to the top repo at time of invoking the plugin.
• _source_dir_host top-level entry is auto-generated by kas-container to track the source
path outside of the container.
• Index
• Module Index
• Search Page
AUTHOR
Daniel Wagner, Jan Kiszka, Claudius Heine
COPYRIGHT
Siemens AG, 2017-2018