User Guide

Dependencies & installation

This projects depends on

  • Python 3
  • distro Python 3 package
  • PyYAML Python 3 package (optional, for yaml file support)

If you need Python 2 support consider sending patches. The most obvious place to start is to use the trollius package intead of asyncio.

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

$ sudo pip3 install .

Usage

There are three options for using kas:

  • Install it locally via pip to get the kas command.
  • Use the docker image. In this case, run the commands in the examples below within docker run -it kasproject/kas:<version> sh or bind-mount the project into the container. See https://hub.docker.com/r/kasproject 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.

Command line usage

kas - setup tool for bitbake based project

usage: kas [-h] [--version] [-d] {build,shell} ...

Positional Arguments

cmd

Possible choices: build, shell

sub command help

Named Arguments

–version show program’s version number and exit
-d, –debug

Enable debug logging

Default: False

Sub-commands:

build

Checks out all necessary repositories and builds using bitbake as specificed in the configuration file.

kas build [-h] [--target TARGET] [--task TASK] [--skip SKIP] config
Positional Arguments
config Config file
Named Arguments
–target Select target to build
–task Select which task should be executed
–skip

Skip build steps

Default: []

shell

Run a shell in the build environment.

kas shell [-h] [--target TARGET] [--skip SKIP] [-k] [-c COMMAND] config
Positional Arguments
config Config file
Named Arguments
–target

Select target to build

Default: “core-image-minimal”

–skip

Skip build steps

Default: []

-k, –keep-config-unchanged
 

Skip steps that change the configuration

Default: False

-c, –command

Run command

Default: “”

Environment variables

Environment variables Description
KAS_WORK_DIR The path of the kas work directory, current work directory is the default.
KAS_REPO_REF_DIR The path to the repository reference directory. Repositories in this directory are user 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”.
KAS_DISTRO KAS_MACHINE KAS_TARGET KAS_TASK This overwrites the respective setting in the configuration file.
SSH_PRIVATE_KEY 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_AGENT_PID SSH_AUTH_SOCK SSH agent process id and authentication socket. Used for cloning over SSH (alternative to SSH_PRIVATE_KEY).
DL_DIR SSTATE_DIR TMPDIR Environment variables that are transferred to the bitbake environment.
http_proxy https_proxy no_proxy This overwrites the proxy configuration in the configuration file.
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.

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
    

Project Configuration

Currently JSON and YAML is supported as the base file format. Since YAML is arguable 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: qemu
# 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 consist 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 (in project scope) for this configuration entries. We assume that your configuration file is part of a meta-custom repository/layer. This way its possible to overwrite or append entries in files that include this configuration by naming an entry the same (overwriting) or using a unused name (appending).

Including in-tree configuration files

Its 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 specified files are addressed relative to your current configuration file.

Including configuration files from other repos

Its 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: exclude

The files are addressed relative to the git repository path.

The include mechanism collects and merges the content from top to buttom 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 recursive 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.

Configuration reference

  • header: dict [required]

    The header of every kas configuration file. It contains information about 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 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 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 repository.
  • 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 qemu.

  • 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]

    Contains the target to build by bitbake. Can be overwritten by the KAS_TARGET environment variable and defaults to core-image-minimal.

  • 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.

      • 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 git repository. If this is missing, no git operations are performed.

      • refspec: string [optional]

        The refspec that should be used. Required if an url was specified.

      • 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.

      • layers: dict [optional]

        Contains the layers from this repository that should be added to the bblayers.conf. If this is missing or None or and empty dictionary, the path to the repo itself is added as a layer.

        • <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.
  • 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 the same order as they are included from the different configuration 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.
  • proxy_config: dict [optional]

    Defines the proxy configuration bitbake should use. Every entry can be overwritten by the respective environment variables.

    • http_proxy: string [optional]
    • https_proxy: string [optional]
    • no_proxy: string [optional]