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.

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.


Setup the logging environment


Ignore SIGINT/SIGTERM in kas, let them be handled by our sub-processes


The actual main entry point of kas.


Creates an argparser for kas with all plugins.


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[source]

The caller environment is not suited for the requested operation

exception kas.libkas.InitBuildEnvError[source]

Error related to the OE / ISAR environment setup scripts

class kas.libkas.LogOutput(live)[source]

Handles the log output of executed applications


This method is called when a line is received over stderr.


This method is called when a line is received over stdout.

exception kas.libkas.TaskExecError(command, ret_code)[source]

Similar to kas.kasusererror.CommandExecError but for kas internal tasks

kas.libkas.find_program(paths, name)[source]

Find a file within the paths array and returns its path.


Creates the build environment variables.


Applies the patches to the repositories.


Fetches the list of repositories to the kas_work_dir.

kas.libkas.run_cmd(cmd, cwd, env=None, fail=True, liveupdate=True)[source]

Runs a command synchronously.

kas.libkas.run_cmd_async(cmd, cwd, env=None, fail=True, liveupdate=True)[source]

Run a command asynchronously.

kas.libkas.ssh_add_key(env, key)[source]

Adds an ssh key to the ssh-agent

kas.libkas.ssh_add_key_file(env, key_path)[source]

Adds an ssh key file to the ssh-agent


Removes the identities and stops the ssh-agent instance


Disables ssh host key check


Starts the ssh-agent

kas.libcmds Module

This module contains common commands used by kas plugins.

class kas.libcmds.CleanupSSHAgent[source]

Removes all the identities and stops the ssh-agent instance.


This method executes the command.

class kas.libcmds.Command[source]

An abstract class that defines the interface of a command.


This method executes the command.

class kas.libcmds.FinishSetupRepos[source]

Finalizes the repo setup loop


This method executes the command.

class kas.libcmds.InitSetupRepos[source]

Prepares setting up repos including the include logic


This method executes the command.

class kas.libcmds.Loop(name)[source]

A class that defines a set of commands as a loop.


Appends a command to the loop.


Executes the loop.

class kas.libcmds.Macro(use_common_setup=True, use_common_cleanup=True)[source]

Contains commands and provides method to run them.


Appends commands to the command list.

run(ctx, skip=None)[source]

Runs a command from the command list with respect to the configuration.

class kas.libcmds.ReposApplyPatches[source]

Applies the patches defined in the configuration to the repositories.


This method executes the command.

class kas.libcmds.ReposCheckout[source]

Ensures that the right revision of each repo is checked out.


This method executes the command.

class kas.libcmds.ReposFetch[source]

Fetches repositories defined in the configuration


This method executes the command.

class kas.libcmds.SetupDir[source]

Creates the build directory.


This method executes the command.

class kas.libcmds.SetupEnviron[source]

Sets up the kas environment.


This method executes the command.

class kas.libcmds.SetupHome[source]

Sets up the home directory of kas.


This method executes the command.

class kas.libcmds.SetupReposStep[source]

Single step of the checkout repos loop


This method executes the command.

class kas.libcmds.SetupSSHAgent[source]

Sets up the ssh agent configuration.


This method executes the command.

class kas.libcmds.WriteBBConfig[source]

Writes bitbake configuration files into the build directory.


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)[source]

Implements the kas configuration based on config files.


Returns repos that are in config but not on disk


Returns the bblayers.conf header


Returns a list of bitbake targets


Returns the bitbake task


Returns the pre-selected build system


Returns the config dict.


Returns the distro


Returns the configured environment variables from the configuration file with possible overwritten values from the environment.


Returns the local.conf header


Returns the machine


Returns the multiconfig array as bitbake string


Returns a Repo instance for the configuration with the key name.


Returns the list of repos.


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)[source]

Provides the git functionality for a Repo.

class kas.repos.MercurialRepo(name, url, path, commit, branch, refspec, layers, patches, disable_operations)[source]

Provides the hg functionality for a Repo.

exception kas.repos.PatchApplyError[source]

The provided patch file could not be applied

exception kas.repos.PatchFileNotFound[source]

The requested patch file was not found

exception kas.repos.PatchMappingError[source]

The requested patch can not be related to a repo

class kas.repos.Repo(name, url, path, commit, branch, refspec, layers, patches, disable_operations)[source]

Represents a repository in the kas configuration.

static factory(name, repo_config, repo_defaults, repo_fallback_path, repo_overrides={})[source]

Returns a Repo instance depending on params.

static get_root_path(path, fallback=True)[source]

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)[source]

Provides a generic implementation for a Repo.


Applies patches to a repository asynchronously.


Checks out the correct revision of the repo.


Starts asynchronous repository fetch.

exception kas.repos.RepoRefError[source]

The requested repo reference is invalid, missing or could not be found

exception kas.repos.UnsupportedRepoTypeError[source]

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[source]

Class for exceptions that appear in the include mechanism.

class kas.includehandler.IncludeHandler(top_files, top_repo_path, use_lock=True)[source]

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.

repos – A dictionary that maps repo names to directory paths
(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)[source]

Class for exceptions that appear while loading a configuration file.


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)[source]

Invalid combination of CLI arguments provided

exception kas.kasusererror.CommandExecError(command, ret_code, forward_ret_code=False)[source]

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[source]

User or input error. Derive all user error exceptions from this class.

kas.plugins Module

This module contains and manages kas plugins


Get a list of all loaded kas plugin classes


Lookup a kas plugin class by name


Import all kas plugins


Register all kas plugins found in a module