Dependencies & installation

This project depends on

To install kas into your python site-package repository, run:

$ sudo pip3 install .

Usage

There are (at least) four options for using 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

$ mkdir $PROJECT_DIR
$ cd $PROJECT_DIR
$ git clone $PROJECT_URL meta-project
$ kas build meta-project/kas-project.yml

$ cd $PROJECT_DIR/meta-project
$ git pull
$ kas build kas-project.yml

$ 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

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:

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:

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"


    refspec: 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"


    refspec: 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"


    refspec: 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:

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.

Configuration reference

repos:


  meta-foo:


    url: https://github.com/bar/meta-foo.git


    path: layers/meta-foo


    refspec: master


    layers:


      .:


      contrib:

Positional Arguments

Named Arguments

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

Named Arguments

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

Named Arguments

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

Named Arguments

shell

Run a shell in the build environment.

kas shell [-h] [--skip SKIP] [--force-checkout] [--update] [-E] [-k]


          [-c COMMAND]


          [config]

Positional Arguments

Named Arguments

menu

Provides a configuration menu and triggers the build of the choices.

kas menu [-h] [kconfig]

Positional Arguments

Environment variables

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

Just run:

$ docker build -t <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.

Community Resources

Project home:

Source code:

Documentation:

Mailing list:

Class reference documentation

kas.kas Module

This module is the main entry point for kas, setup tool for bitbake based projects

kas.libkas Module

This module contains the core implementation of kas.

kas.libcmds Module

This module contains common commands used by kas plugins.

kas.config Module

This module contains the implementation of the kas configuration.

kas.repos Module

This module contains the Repo class.

kas.includehandler Module

This module implements how includes of configuration files are handled in kas.

kas.plugins Module

This module contains and manages kas plugins

Version 1 (Alias '0.10')

Added

Version 2

Changed

Fixed

Version 3

Added

Version 4

Added

Version 5

Changed behavior

Version 6

Added

Version 7

Added

Version 8

Added

Version 9

Added

Version 10

Added

Version 11

Changed behavior

Added

Version 12

Added