.\" Man page generated from reStructuredText.
.
.TH "KAS" "1" "Mar 14, 2021" "2.3.3" "kas"
.SH NAME
kas \- kas Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
This tool provides an easy mechanism to setup bitbake based
projects.
.sp
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.
.sp
Key features provided by the build tool:
.INDENT 0.0
.IP \(bu 2
clone and checkout bitbake layers
.IP \(bu 2
create default bitbake settings (machine, arch, ...)
.IP \(bu 2
launch minimal build environment, reducing risk of host contamination
.IP \(bu 2
initiate bitbake build process
.UNINDENT
.SH USER GUIDE
.SS Dependencies & installation
.sp
This project depends on
.INDENT 0.0
.IP \(bu 2
Python 3
.IP \(bu 2
distro Python 3 package
.IP \(bu 2
jsonschema Python 3 package
.IP \(bu 2
PyYAML Python 3 package (optional, for yaml file support)
.UNINDENT
.sp
To install kas into your python site\-package repository, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sudo pip3 install .
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Usage
.sp
There are (at least) four options for using kas:
.INDENT 0.0
.IP \(bu 2
Install it locally via pip to get the \fBkas\fP command.
.IP \(bu 2
Use the container image locally. In this case, download the \fBkas\-container\fP
script from the kas repository and use it in place of the \fBkas\fP command.
The script version corresponds to the kas tool and the kas image version.
.IP \(bu 2
Use the container image in CI. Specify
\fBghcr.io/siemens/kas/kas[\-isar][:<x.y>]\fP in your CI script that requests
a container image as runtime environment. See
\fI\%https://github.com/orgs/siemens/packages/container/kas%2Fkas/31765\fP and
\fI\%https://github.com/orgs/siemens/packages/container/kas%2Fkas\-isar/31794\fP for
all available images.
.IP \(bu 2
Use the \fBrun\-kas\fP wrapper from this directory. In this case,
replace \fBkas\fP in the examples below with \fBpath/to/run\-kas\fP\&.
.UNINDENT
.sp
Start build:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ kas build /path/to/kas\-project.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, experienced bitbake users can invoke usual \fBbitbake\fP steps
manually, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ kas shell /path/to/kas\-project.yml \-c \(aqbitbake dosfsutils\-native\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
kas will place downloads and build artifacts under the current directory when
being invoked. You can specify a different location via the environment
variable \fIKAS_WORK_DIR\fP\&.
.SS Use Cases
.INDENT 0.0
.IP 1. 3
Initial build/setup:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ mkdir $PROJECT_DIR
$ cd $PROJECT_DIR
$ git clone $PROJECT_URL meta\-project
$ kas build meta\-project/kas\-project.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Update/rebuild:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ cd $PROJECT_DIR/meta\-project
$ git pull
$ kas build kas\-project.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Plugins
.sp
kas sub\-commands are implemented by a series of plugins. Each plugin
typically provides a single command.
.SS \fBbuild\fP plugin
.sp
This plugin implements the \fBkas build\fP command.
.sp
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.
.sp
For example, to build the configuration described in the file
\fBkas\-project.yml\fP you could run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas build kas\-project.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBcheckout\fP plugin
.sp
This plugin implements the \fBkas checkout\fP command.
.sp
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.
.sp
For example, to setup the configuration described in the file
\fBkas\-project.yml\fP you could run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas checkout kas\-project.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBfor\-all\-repos\fP plugin
.sp
This plugin implements the \fBkas for\-all\-repos\fP command.
.sp
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.
.sp
For example, to print the commit hashes used by each repository used in
the file \fBkas\-project.yml\fP (assuming they are all git repositories) you
could run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas for\-all\-repos kas\-project.yml \(aqgit rev\-parse HEAD\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The environment for executing the command in each repository is extended
to include the following variables:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBKAS_REPO_NAME\fP: The name of the current repository determined by
either the name property or by the key used for this repo in the config
file.
.IP \(bu 2
\fBKAS_REPO_PATH\fP: The path of the local directory where this
repository is checked out, relative to the directory where \fBkas\fP is
executed.
.IP \(bu 2
\fBKAS_REPO_URL\fP: The URL from which this repository was cloned, or an
empty string if no remote URL was given in the config file.
.IP \(bu 2
\fBKAS_REPO_REFSPEC\fP: The refspec which was checked out for this
repository, or an empty string if no refspec was given in the config
file.
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fBshell\fP plugin
.sp
This plugin implements the \fBkas shell\fP command.
.sp
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 \fBbitbake\fP with custom command line options
or to execute other commands such as \fBrunqemu\fP\&.
.sp
For example, to start a shell in the build environment for the file
\fBkas\-project.yml\fP you could run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas shell kas\-project.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or to invoke qemu to test an image which has been built:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas shell kas\-project.yml \-c \(aqrunqemu\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Project Configuration
.sp
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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Every file needs to contain a header, that provides kas with information
# about the context of this file.
header:
  # The \(gaversion\(ga 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 \(galocal.conf\(ga of bitbake.
machine: qemux86\-64
# The distro name as it is written into the \(galocal.conf\(ga 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:
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A minimal input file consists out of the \fBheader\fP, \fBmachine\fP, \fBdistro\fP,
and \fBrepos\fP\&.
.sp
Additionally, you can add \fBbblayers_conf_header\fP and \fBlocal_conf_header\fP
which are strings that are added to the head of the respective files
(\fBbblayers.conf\fP or \fBlocal.conf\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBmeta\-custom\fP 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 \fBmeta\-custom\fP 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 an unused name (appending).
.SS Including in\-tree configuration files
.sp
It\(aqs currently possible to include kas configuration files from the same
repository/layer like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
header:
  version: x
  includes:
    \- base.yml
    \- bsp.yml
    \- product.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The specified files are addressed relative to your current configuration file.
.SS Including configuration files from other repos
.sp
It\(aqs also possible to include configuration files from other repos like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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 \(gakas\-poky.yml\(ga adds the \(gameta\-yocto\-bsp\(ga layer and we
      # do not want it in our bblayers for this project, we can
      # overwrite it by setting:
      meta\-yocto\-bsp: exclude
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The files are addressed relative to the git repository path.
.sp
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 \fBlocal_conf_header\fP entries are added to the
\fBlocal.conf\fP 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.
.SS Including configuration files via the command line
.sp
When specifying the kas configuration file on the command line, additional
configurations can be included ad\-hoc:
.INDENT 0.0
.INDENT 3.5
$ kas build kas\-base.yml:debug\-image.yml:board.yml
.UNINDENT
.UNINDENT
.sp
This is equivalent to static inclusion from some kas\-combined.yml like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
header:
  version: x
  includes:
    \- kas\-base.yml
    \- debug.image.yml
    \- board.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Command line inclusion allows to create configurations on\-demand, without the
need to write a kas configuration file for each possible combination.
.sp
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.
.SS Configuration reference
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBheader\fP: dict [required]
The header of every kas configuration file. It contains information about
the context of the file.
.INDENT 7.0
.TP
.B \fBversion\fP: 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.
.TP
.B \fBincludes\fP: 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:
.INDENT 7.0
.TP
.B item: string
The path to a kas configuration file, relative to the current file.
.TP
.B item: dict
If files from other repositories should be included, choose this
representation.
.INDENT 7.0
.TP
.B \fBrepo\fP: string [required]
The id of the repository where the file is located. The repo
needs to be defined in the \fBrepos\fP dictionary as \fB<repo\-id>\fP\&.
.TP
.B \fBfile\fP: string [required]
The path to the file relative to the root of the repository.
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B \fBbuild_system\fP: string [optional]
Defines the bitbake\-based build system. Known build systems are
\fBopenembedded\fP (or \fBoe\fP) and \fBisar\fP\&. If set, this restricts the
search of kas for the init script in the configured repositories to
\fBoe\-init\-build\-env\fP or \fBisar\-init\-build\-env\fP, respectively. If
\fBkas\-container\fP 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.
.TP
.B \fBdefaults\fP: 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 refspec for
all repositories.
.INDENT 7.0
.TP
.B \fBrepos\fP: 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.
.INDENT 7.0
.TP
.B \fBrefspec\fP: string [optional]
Sets the default \fBrefspec\fP property applied to all repositories that
do not override this.
.TP
.B \fBpatches\fP: 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.
.INDENT 7.0
.TP
.B \fBrepo\fP: string [optional]
Sets the default \fBrepo\fP property applied to all repository
patches that do not override this.
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B \fBmachine\fP: string [optional]
Contains the value of the \fBMACHINE\fP variable that is written into the
\fBlocal.conf\fP\&. Can be overwritten by the \fBKAS_MACHINE\fP environment
variable and defaults to \fBqemux86\-64\fP\&.
.TP
.B \fBdistro\fP: string [optional]
Contains the value of the \fBDISTRO\fP variable that is written into the
\fBlocal.conf\fP\&. Can be overwritten by the \fBKAS_DISTRO\fP environment
variable and defaults to \fBpoky\fP\&.
.TP
.B \fBtarget\fP: string [optional] or list [optional]
Contains the target or a list of targets to build by bitbake. Can be
overwritten by the \fBKAS_TARGET\fP environment variable and defaults to
\fBcore\-image\-minimal\fP\&. Space is used as a delimiter if multiple targets
should be specified via the environment variable.
.TP
.B \fBenv\fP: dict [optional]
Contains environment variable names with the default values. These
variables are made available to bitbake via \fBBB_ENV_EXTRAWHITE\fP and can
be overwritten by the variables of the environment in which kas is started.
.TP
.B \fBtask\fP: string [optional]
Contains the task to build by bitbake. Can be overwritten by the
\fBKAS_TASK\fP environment variable and defaults to \fBbuild\fP\&.
.TP
.B \fBrepos\fP: dict [optional]
Contains the definitions of all available repos and layers.
.INDENT 7.0
.TP
.B \fB<repo\-id>\fP: dict [optional]
Contains the definition of a repository and the layers, that should be
part of the build. If the value is \fBNone\fP, the repository, where the
current configuration file is located is defined as \fB<repo\-id>\fP and
added as a layer to the build.
.INDENT 7.0
.TP
.B \fBname\fP: string [optional]
Defines under which name the repository is stored. If its missing
the \fB<repo\-id>\fP will be used.
.TP
.B \fBurl\fP: string [optional]
The url of the repository. If this is missing, no version control
operations are performed.
.TP
.B \fBtype\fP: string [optional]
The type of version control repository. The default value is \fBgit\fP
and \fBhg\fP is also supported.
.TP
.B \fBrefspec\fP: string [optional]
The refspec that should be used. If \fBurl\fP was specified but no
\fBrefspec\fP the revision you get depends on the defaults of the version
control system used.
.TP
.B \fBpath\fP: string [optional]
The path where the repository is stored.
If the \fBurl\fP and \fBpath\fP is missing, the repository where the
current configuration file is located is defined.
If the \fBurl\fP is missing and the path defined, this entry references
the directory the path points to.
If the \fBurl\fP as well as the \fBpath\fP is defined, the path is used to
overwrite the checkout directory, that defaults to \fBkas_work_dir\fP
+ \fBrepo.name\fP\&.
In case of a relative path name \fBkas_work_dir\fP is prepended.
.TP
.B \fBlayers\fP: dict [optional]
Contains the layers from this repository that should be added to the
\fBbblayers.conf\fP\&. If this is missing or \fBNone\fP or and empty
dictionary, the path to the repo itself is added as a layer.
.INDENT 7.0
.TP
.B \fB<layer\-path>\fP: enum [optional]
Adds the layer with \fB<layer\-path>\fP that is relative to the
repository root directory, to the \fBbblayers.conf\fP if the value of
this entry is not in this list: \fB[\(aqdisabled\(aq, \(aqexcluded\(aq, \(aqn\(aq, \(aqno\(aq,
\(aq0\(aq, \(aqfalse\(aq]\fP\&. This way it is possible to overwrite the inclusion
of a layer in latter loaded configuration files.
.UNINDENT
.TP
.B \fBpatches\fP: dict [optional]
Contains the patches that should be applied to this repo before it is
used.
.INDENT 7.0
.TP
.B \fB<patches\-id>\fP: dict [optional]
One entry in patches with its specific and unique id. All available
patch entries are applied in the order of their sorted
\fB<patches\-id>\fP\&.
.INDENT 7.0
.TP
.B \fBrepo\fP: string [required]
The identifier of the repo where the path of this entry is relative
to.
.TP
.B \fBpath\fP: string [required]
The path to one patch file or a quilt formatted patchset directory.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B \fBbblayers_conf_header\fP: dict [optional]
This contains strings that should be added to the \fBbblayers.conf\fP before
any layers are included.
.INDENT 7.0
.TP
.B \fB<bblayers\-conf\-id>\fP: string [optional]
A string that is added to the \fBbblayers.conf\fP\&. The entry id
(\fB<bblayers\-conf\-id>\fP) 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 \fBbblayers.conf\fP in the same order
as they are included from the different configuration files.
.UNINDENT
.TP
.B \fBlocal_conf_header\fP: dict [optional]
This contains strings that should be added to the \fBlocal.conf\fP\&.
.INDENT 7.0
.TP
.B \fB<local\-conf\-id>\fP: string [optional]
A string that is added to the \fBlocal.conf\fP\&. It operates in the same way
as the \fBbblayers_conf_header\fP entry.
.UNINDENT
.TP
.B \fBproxy_config\fP: dict [optional]
Defines the proxy configuration bitbake should use. Every entry can be
overwritten by the respective environment variables.
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fBhttp_proxy\fP: string [optional]
.IP \(bu 2
\fBhttps_proxy\fP: string [optional]
.IP \(bu 2
\fBno_proxy\fP: string [optional]
.UNINDENT
.UNINDENT
.UNINDENT
.SH COMMAND LINE USAGE
.sp
kas \- setup tool for bitbake based project

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: kas [\-h] [\-\-version] [\-d] {build,checkout,for\-all\-repos,shell} ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B cmd
Possible choices: build, checkout, for\-all\-repos, shell
.sp
sub command help
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-\-version
show program\(aqs version number and exit
.TP
.B \-d, \-\-debug
Enable debug logging
.sp
Default: False
.UNINDENT
.SS Sub\-commands:
.SS build
.sp
Checks out all necessary repositories and builds using bitbake as specified in the configuration file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas build [\-h] [\-\-skip SKIP] [\-\-force\-checkout] [\-\-update] [\-\-target TARGET]
          [\-c TASK]
          config [extra_bitbake_args ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B config
Config file
.TP
.B extra_bitbake_args
Extra arguments to pass to bitbake
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-\-skip
Skip build steps
.sp
Default: []
.TP
.B \-\-force\-checkout
Always checkout the desired refspec of each repository, discarding any local changes
.sp
Default: False
.TP
.B \-\-update
Pull new upstream changes to the desired refspec even if it is already checked out locally
.sp
Default: False
.TP
.B \-\-target
Select target to build
.TP
.B \-c, \-\-cmd, \-\-task
Select which task should be executed
.UNINDENT
.SS checkout
.sp
Checks out all necessary repositories and sets up the build directory as specified in the configuration file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas checkout [\-h] [\-\-skip SKIP] [\-\-force\-checkout] [\-\-update] config
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B config
Config file
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-\-skip
Skip build steps
.sp
Default: []
.TP
.B \-\-force\-checkout
Always checkout the desired refspec of each repository, discarding any local changes
.sp
Default: False
.TP
.B \-\-update
Pull new upstream changes to the desired refspec even if it is already checked out locally
.sp
Default: False
.UNINDENT
.SS for\-all\-repos
.sp
Runs a specified command in all checked out repositories.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas for\-all\-repos [\-h] [\-\-skip SKIP] [\-\-force\-checkout] [\-\-update]
                  config command
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B config
Config file
.TP
.B command
Command to be executed as a string.
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-\-skip
Skip build steps
.sp
Default: []
.TP
.B \-\-force\-checkout
Always checkout the desired refspec of each repository, discarding any local changes
.sp
Default: False
.TP
.B \-\-update
Pull new upstream changes to the desired refspec even if it is already checked out locally
.sp
Default: False
.UNINDENT
.SS shell
.sp
Run a shell in the build environment.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kas shell [\-h] [\-\-skip SKIP] [\-\-force\-checkout] [\-\-update] [\-k] [\-c COMMAND]
          config
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B config
Config file
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-\-skip
Skip build steps
.sp
Default: []
.TP
.B \-\-force\-checkout
Always checkout the desired refspec of each repository, discarding any local changes
.sp
Default: False
.TP
.B \-\-update
Pull new upstream changes to the desired refspec even if it is already checked out locally
.sp
Default: False
.TP
.B \-k, \-\-keep\-config\-unchanged
Skip steps that change the configuration
.sp
Default: False
.TP
.B \-c, \-\-command
Run command
.sp
Default: ""
.UNINDENT
.SS Environment variables
.TS
center;
|l|l|.
_
T{
Environment variables
T}	T{
Description
T}
_
T{
\fBKAS_WORK_DIR\fP
T}	T{
The path of the kas work directory, current work
directory is the default.
T}
_
T{
\fBKAS_REPO_REF_DIR\fP
T}	T{
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: "\fI\%https://github.com/siemens/meta\-iot2000.git\fP"
resolves to the name
"github.com.siemens.meta\-iot2000.git".
T}
_
T{
\fBKAS_DISTRO\fP
\fBKAS_MACHINE\fP
\fBKAS_TARGET\fP
\fBKAS_TASK\fP
T}	T{
This overwrites the respective setting in the
configuration file.
T}
_
T{
\fBKAS_PREMIRRORS\fP
T}	T{
Specifies alternatives for repo URLs. Just like
bitbake \fBPREMIRRORS\fP, 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.:
"\fI\%https://.*.somehost.io/\fP \fI\%https://localmirror.net/\fP"
T}
_
T{
\fBSSH_PRIVATE_KEY\fP
T}	T{
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.
T}
_
T{
\fBSSH_AUTH_SOCK\fP
T}	T{
SSH authentication socket. Used for cloning over
SSH (alternative to \fBSSH_PRIVATE_KEY\fP).
T}
_
T{
\fBDL_DIR\fP
\fBSSTATE_DIR\fP
\fBTMPDIR\fP
T}	T{
Environment variables that are transferred to the
bitbake environment.
T}
_
T{
\fBhttp_proxy\fP
\fBhttps_proxy\fP
\fBftp_proxy\fP
\fBno_proxy\fP
T}	T{
This overwrites the proxy configuration in the
configuration file.
T}
_
T{
\fBGIT_PROXY_COMMAND\fP
\fBNO_PROXY\fP
T}	T{
Set proxy for native git fetches. \fBNO_PROXY\fP is
evaluated by OpenEmbedded\(aqs oe\-git\-proxy script.
T}
_
T{
\fBSHELL\fP
T}	T{
The shell to start when using the \fIshell\fP plugin.
T}
_
T{
\fBTERM\fP
T}	T{
The terminal options used in the \fIshell\fP plugin.
T}
_
T{
\fBAWS_CONFIG_FILE\fP
\fBAWS_SHARED_CREDENTIALS_FILE\fP
T}	T{
Path to the awscli configuration and credentials
file that are copied to the kas home dir.
T}
_
.TE
.SH DEVELOPER GUIDE
.SS Deploy for development
.sp
This project uses pip to manage the package. If you want to work on the
project yourself you can create the necessary links via:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip3 install \-\-user \-e .
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That will install a backlink ~/.local/bin/kas to this project. Now you are
able to call it from anywhere.
.SS Docker image build
.sp
Just run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ docker build \-t <image_name> .
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When you need a proxy to access the internet, add:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-build\-arg http_proxy=<http_proxy> \-\-build\-arg https_proxy=<https_proxy> \-\-build\-arg ftp_proxy=<ftp_proxy> \-\-build\-arg no_proxy=<no_proxy>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to the call.
.SS Community Resources
.sp
Project home:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%https://github.com/siemens/kas\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Source code:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%https://github.com/siemens/kas.git\fP
.IP \(bu 2
\fI\%git@github.com\fP:siemens/kas.git
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Documentation:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%https://kas.readthedocs.org\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Mailing list:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%kas\-devel@googlegroups.com\fP
.IP \(bu 2
Subscription:
.INDENT 2.0
.IP \(bu 2
\fI\%kas\-devel+subscribe@googlegroups.com\fP
.IP \(bu 2
\fI\%https://groups.google.com/forum/#!forum/kas\-devel/join\fP
.UNINDENT
.IP \(bu 2
Archives
.INDENT 2.0
.IP \(bu 2
\fI\%https://groups.google.com/forum/#!forum/kas\-devel\fP
.IP \(bu 2
\fI\%https://www.mail\-archive.com/kas\-devel@googlegroups.com/\fP
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Class reference documentation
.SS \fBkas.kas\fP Module
.sp
This module is the main entry point for kas, setup tool for bitbake based
projects
.INDENT 0.0
.TP
.B kas.kas.create_logger()
Setup the logging environment
.UNINDENT
.INDENT 0.0
.TP
.B kas.kas.interruption()
Ignore SIGINT/SIGTERM in kas, let them be handled by our sub\-processes
.UNINDENT
.INDENT 0.0
.TP
.B kas.kas.kas(argv)
The actual main entry point of kas.
.UNINDENT
.INDENT 0.0
.TP
.B kas.kas.kas_get_argparser()
Creates an argparser for kas with all plugins.
.UNINDENT
.INDENT 0.0
.TP
.B kas.kas.main()
The main function that operates as a wrapper around kas.
.UNINDENT
.SS \fBkas.libkas\fP Module
.sp
This module contains the core implementation of kas.
.INDENT 0.0
.TP
.B class kas.libkas.LogOutput(live)
Handles the log output of executed applications
.INDENT 7.0
.TP
.B log_stderr(line)
This method is called when a line is received over stderr.
.UNINDENT
.INDENT 7.0
.TP
.B log_stdout(line)
This method is called when a line is received over stdout.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.find_program(paths, name)
Find a file within the paths array and returns its path.
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.get_build_environ(build_system)
Creates the build environment variables.
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.repos_apply_patches(repos)
Applies the patches to the repositories.
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.repos_fetch(repos)
Fetches the list of repositories to the kas_work_dir.
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.run_cmd(cmd, cwd, env=None, fail=True, liveupdate=True)
Runs a command synchronously.
.UNINDENT
.INDENT 0.0
.TP
.B async kas.libkas.run_cmd_async(cmd, cwd, env=None, fail=True, liveupdate=True)
Run a command asynchronously.
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.ssh_add_key(env, key)
Adds an ssh key to the ssh\-agent
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.ssh_cleanup_agent()
Removes the identities and stops the ssh\-agent instance
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.ssh_no_host_key_check()
Disables ssh host key check
.UNINDENT
.INDENT 0.0
.TP
.B kas.libkas.ssh_setup_agent(envkeys=None)
Starts the ssh\-agent
.UNINDENT
.SS \fBkas.libcmds\fP Module
.sp
This module contains common commands used by kas plugins.
.INDENT 0.0
.TP
.B class kas.libcmds.CleanupSSHAgent
Removes all the identities and stops the ssh\-agent instance.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.Command
An abstract class that defines the interface of a command.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.FinishSetupRepos
Finalizes the repo setup loop
.INDENT 7.0
.TP
.B execute(ctx)
TODO refactor protected\-access
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.InitSetupRepos
Prepares setting up repos including the include logic
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.Loop(name)
A class that defines a set of commands as a loop.
.INDENT 7.0
.TP
.B add(command)
Appends a command to the loop.
.UNINDENT
.INDENT 7.0
.TP
.B execute(ctx)
Executes the loop.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.Macro(use_common_setup=True, use_common_cleanup=True)
Contains commands and provides method to run them.
.INDENT 7.0
.TP
.B add(command)
Appends commands to the command list.
.UNINDENT
.INDENT 7.0
.TP
.B run(ctx, skip=None)
Runs a command from the command list with respect to the
configuration.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.ReposApplyPatches
Applies the patches defined in the configuration to the repositories.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.ReposCheckout
Ensures that the right revision of each repo is checked out.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.ReposFetch
Fetches repositories defined in the configuration
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.SetupDir
Creates the build directory.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.SetupEnviron
Sets up the kas environment.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.SetupHome
Sets up the home directory of kas.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.SetupReposStep
Single step of the checkout repos loop
.INDENT 7.0
.TP
.B execute(ctx)
TODO refactor protected\-access
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.SetupSSHAgent
Sets up the ssh agent configuration.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.libcmds.WriteBBConfig
Writes bitbake configuration files into the build directory.
.INDENT 7.0
.TP
.B execute(ctx)
This method executes the command.
.UNINDENT
.UNINDENT
.SS \fBkas.config\fP Module
.sp
This module contains the implementation of the kas configuration.
.INDENT 0.0
.TP
.B class kas.config.Config(filename, target=None, task=None)
Implements the kas configuration based on config files.
.INDENT 7.0
.TP
.B find_missing_repos()
Returns repos that are in config but not on disk
.UNINDENT
.INDENT 7.0
.TP
.B get_bblayers_conf_header()
Returns the bblayers.conf header
.UNINDENT
.INDENT 7.0
.TP
.B get_bitbake_targets()
Returns a list of bitbake targets
.UNINDENT
.INDENT 7.0
.TP
.B get_bitbake_task()
Returns the bitbake task
.UNINDENT
.INDENT 7.0
.TP
.B get_build_system()
Returns the pre\-selected build system
.UNINDENT
.INDENT 7.0
.TP
.B get_distro()
Returns the distro
.UNINDENT
.INDENT 7.0
.TP
.B get_environment()
Returns the configured environment variables from the configuration
file with possible overwritten values from the environment.
.UNINDENT
.INDENT 7.0
.TP
.B get_local_conf_header()
Returns the local.conf header
.UNINDENT
.INDENT 7.0
.TP
.B get_machine()
Returns the machine
.UNINDENT
.INDENT 7.0
.TP
.B get_multiconfig()
Returns the multiconfig array as bitbake string
.UNINDENT
.INDENT 7.0
.TP
.B get_repos()
Returns the list of repos.
.UNINDENT
.UNINDENT
.SS \fBkas.repos\fP Module
.sp
This module contains the Repo class.
.INDENT 0.0
.TP
.B class kas.repos.GitRepo(name, url, path, refspec, layers, patches, disable_operations)
Provides the git functionality for a Repo.
.UNINDENT
.INDENT 0.0
.TP
.B class kas.repos.MercurialRepo(name, url, path, refspec, layers, patches, disable_operations)
Provides the hg functionality for a Repo.
.UNINDENT
.INDENT 0.0
.TP
.B class kas.repos.Repo(name, url, path, refspec, layers, patches, disable_operations)
Represents a repository in the kas configuration.
.INDENT 7.0
.TP
.B static factory(name, repo_config, repo_defaults, repo_fallback_path)
Returns a Repo instance depending on params.
.UNINDENT
.INDENT 7.0
.TP
.B static get_root_path(path, fallback=True)
Checks if path is under version control and returns its root path.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class kas.repos.RepoImpl(name, url, path, refspec, layers, patches, disable_operations)
Provides a generic implementation for a Repo.
.INDENT 7.0
.TP
.B async apply_patches_async()
Applies patches to a repository asynchronously.
.UNINDENT
.INDENT 7.0
.TP
.B checkout()
Checks out the correct revision of the repo.
.UNINDENT
.INDENT 7.0
.TP
.B async fetch_async()
Starts asynchronous repository fetch.
.UNINDENT
.UNINDENT
.SS \fBkas.includehandler\fP Module
.sp
This module implements how includes of configuration files are handled in
kas.
.INDENT 0.0
.TP
.B exception kas.includehandler.IncludeException
Class for exceptions that appear in the include mechanism.
.UNINDENT
.INDENT 0.0
.TP
.B class kas.includehandler.IncludeHandler(top_files)
Implements a handler where every configuration file should
contain a dictionary as the base type with and \(aqincludes\(aq
key containing a list of includes.
.sp
The includes can be specified in two ways: as a string
containing the relative path from the current file or as a
dictionary. The dictionary should have a \(aqfile\(aq key containing
the relative path to the include file and optionally a \(aqrepo\(aq
key containing the key of the repository. If the \(aqrepo\(aq key is
missing the value of the \(aqfile\(aq key, it is treated the same as if
just a string was defined, meaning the path is relative to the
current config file. Otherwise it is interpreted relative to
the repository path.
.sp
The includes are read and merged from the deepest level upwards.
.INDENT 7.0
.TP
.B get_config(repos=None)
.INDENT 7.0
.TP
.B Parameters:
repos \-\- A dictionary that maps repo names to directory paths
.TP
.B Returns:
.INDENT 7.0
.TP
.B (config, repos)
config \-\- A dictionary containing the configuration
repos \-\- A list of missing repo names that are needed                      to create a complete configuration
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B exception kas.includehandler.LoadConfigException(message, filename)
Class for exceptions that appear while loading a configuration file.
.UNINDENT
.INDENT 0.0
.TP
.B kas.includehandler.load_config(filename)
Load the configuration file and test if version is supported.
.UNINDENT
.SS \fBkas.plugins\fP Module
.sp
This module contains and manages kas plugins
.INDENT 0.0
.TP
.B kas.plugins.all()
Get a list of all loaded kas plugin classes
.UNINDENT
.INDENT 0.0
.TP
.B kas.plugins.get(name)
Lookup a kas plugin class by name
.UNINDENT
.INDENT 0.0
.TP
.B kas.plugins.load()
Import all kas plugins
.UNINDENT
.INDENT 0.0
.TP
.B kas.plugins.register_plugins(mod)
Register all kas plugins found in a module
.UNINDENT
.SH CONFIGURATION FORMAT CHANGES
.SS Version 1 (Alias \(aq0.10\(aq)
.SS Added
.INDENT 0.0
.IP \(bu 2
Include mechanism
.IP \(bu 2
Version check
.UNINDENT
.SS Version 2
.SS Changed
.INDENT 0.0
.IP \(bu 2
Configuration file versions are now integers
.UNINDENT
.SS Fixed
.INDENT 0.0
.IP \(bu 2
Including files from repos that are not defined in the current file
.UNINDENT
.SS Version 3
.SS Added
.INDENT 0.0
.IP \(bu 2
\fBTask\fP key that allows to specify which task to run (\fBbitbake \-c\fP)
.UNINDENT
.SS Version 4
.SS Added
.INDENT 0.0
.IP \(bu 2
\fBTarget\fP key now allows to be a list of target names
.UNINDENT
.SS Version 5
.SS Changed behavior
.INDENT 0.0
.IP \(bu 2
Using \fBmulticonfig:*\fP targets adds appropriate \fBBBMULTICONFIG\fP entries to
the \fBlocal.conf\fP automatically.
.UNINDENT
.SS Version 6
.SS Added
.INDENT 0.0
.IP \(bu 2
\fBenv\fP key now allows to pass custom environment variables to the bitbake
build process.
.UNINDENT
.SS Version 7
.SS Added
.INDENT 0.0
.IP \(bu 2
\fBtype\fP property to \fBrepos\fP to be able to express which version control
system to use.
.UNINDENT
.SS Version 8
.SS Added
.INDENT 0.0
.IP \(bu 2
\fBpatches\fP property to \fBrepos\fP to be able to apply additional patches to
the repo.
.UNINDENT
.SS Version 9
.SS Added
.INDENT 0.0
.IP \(bu 2
\fBdefaults\fP key can now be used to set a default value for the repository
property \fBrefspec\fP and the repository patch property \fBrepo\fP\&. These
default values will be used if the appropriate properties are not defined
for a given repository or patch.
.UNINDENT
.SS Version 10
.SS Added
.INDENT 0.0
.IP \(bu 2
\fBbuild_system\fP property to pre\-select OE or Isar.
.UNINDENT
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
modindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
Daniel Wagner, Jan Kiszka, Claudius Heine
.SH COPYRIGHT
Siemens AG, 2017-2018
.\" Generated by docutils manpage writer.
.