KAS-PROJECT-CONFIG(1)

NAME
kas-project-config - kas project configuration

PROJECT CONFIGURATION

Currently, JSON and YAML 1.1 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).

Note:
        kas internally uses PyYAML to parse YAML documents, inheriting its limitations. Notably, PyYAML only supports YAML 1.1 and does not correctly handle non-string keys in mappings. To avoid this issue, we recommend quoting keys of other types, such as octal numbers (0001), integers (42), booleans (false) and special values (no).

  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

If 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 and must not traverse outside of the referenced repo.

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.

Warning:
        The include mechanism does not support circular references with respect to the repos entries. By that, a (transitive) include file must not change the reference of the repository it is included from.

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. The header.version property is always set to the highest version number found in the config files.

Note:
        Internally kas iterates the repository checkout step until all referenced repositories are resolved (checked out). After each iteration, the (partial) configuration is merged and the next iteration is started. Once all repositories are available, the final configuration is build. Then, all remaining repositories are checked out.

  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 one to create configurations on-demand, without the need to write a kas configuration file for each possible combination.

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.

Note:
        Git submodules are considered to be part of the main repository. Hence, including config files from a submodule is supported. The repository root is always the root of the main repository (if under VCS) or the directory of the first kas config file otherwise.

  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 currently processed kas file. If this is found, kas loads this file right before processing the current one (similar to an include file).

Note:
        The locking logic applies to both files on the kas cmdline and include files.

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 lock plugin provides helpers to simplify the creation and update of lockfiles. For details, see the plugins documentation: kas.plugins.lock <#module-kas.plugins.lock>.

  Configuration reference

    header: dict [required]
        Header of every kas configuration file. It contains information about the context of the file.

        version: integer [required]
            Version of the configuration file format. See the configuration format changelog <> for the format history and the latest available version.

        includes: list [optional]
            List of configuration files to include (parsed depth-first). 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
                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 (dict) representation.

                repo: string [required]
                    Repository key the configuration file is located in. The repo needs to be defined in the repos dictionary as <repo-id>.

                file: string [required]
                    Path to the configuration file relative to the repository.

    build_system: string [optional]
        Defines the bitbake-based build system. openembedded and oe are equivalent. isar is deprecated, use isar-privileged or isar-rootless instead.

        Default: openembedded

        Supported values: openembedded, oe, isar, isar-privileged, isar-rootless

        This value determines which init script is searched for in the configured repositories (oe-init-build-env or isar-init-build-env, respectively). kas-container evaluates this property in the top-level kas configuration file only (includes are not evaluated) to select the required container image and invocation mode.

        Note:
            Modern versions of isar support a rootless mode, whereby builds can be executed as non-privileged user. To distinguish the two modes, use isar-rootless or isar-privileged. Whether the rootless mode is supported depends on your layers.

    defaults: dict [optional]
        Default values applied to all configuration nodes. 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]
            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]
                Default branch property applied to all repositories that do not override this.

            tag: string [optional]
                Default tag property applied to all repositories that do not override this.

            patches: dict [optional]
                Default patches to apply to all repositories. 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]
        Value of the MACHINE variable that is written into the local.conf. Can be overwritten by the KAS_MACHINE environment variable.

        Default: qemux86-64

    distro: string [optional]
        Value of the DISTRO variable that is written into the local.conf. Can be overwritten by the KAS_DISTRO environment variable.

        Default: nodistro

    target: string [optional] or list [optional]
        Single target or a list of targets to build by bitbake. Can be overwritten by the KAS_TARGET environment variable. Space is used as a delimiter if multiple targets should be specified via the environment variable. For targets prefixed with multiconfig: or mc:, corresponding entries are added to the BBMULTICONFIG in local.conf.

        Default: core-image-minimal

    env: dict [optional]
        Environment variables to forward and their default values (set to nulltype to only forward if set). These variables are made available to bitbake via BB_ENV_PASSTHROUGH_ADDITIONS (BB_ENV_EXTRAWHITE in older Bitbake versions) and can be overwritten by the variables of the environment in which kas is started. Either a string or nothing (null) 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_PASSTHROUGH_ADDITIONS and not to the environment where kas is started. Please note, that null needs to be assigned as the nulltype (e.g. MYVAR: null), not as 'null'.

    task: string [optional]
        Task to build by bitbake. Can be overwritten by the KAS_TASK environment variable.

        Default: build

    repos: dict [optional]
        Definitions of all available repos and layers. The layers are appended to the bblayers.conf sorted by the layer priority first (descending), then repository name and then by the layer name (ascending).

        <repo-id>: dict [optional]
            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]
                URL of the repository. If this is missing, no version control operations are performed.

            type: string [optional]
                Type of version control repository.

                Default: git

                Supported values: git, hg

            commit: string [optional]
                Full-length commit ID (all-lowercase, no branch names, no symbolic refs, no tags) that should be used. If url was specified but no commit, branch or tag, the revision you get depends on the defaults of the version control system used.

            branch: string or nothing (null) [optional]
                Upstream branch that should be tracked. If commit was specified, kas checks that the branch contains the commit. If no commit was specified, the head of the upstream branch is checked out. The nothing (null) value is used to remove a possible default value.

            tag: string or nothing (null) [optional]
                Tag that should be checked out. If a commit was specified, kas checks that the tag points to this commit. This must not be combined with branch. The nothing (null) value is used to remove a possible default value.

            path: string [optional]
                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.

            signed: boolean [optional]
                Whether the commit / tag must be signed. If enabled, 'allowed_signers' must be defined. If both tag and commit are specified, only the signature of the tag is checked. Git only.

                Default: False

            allowed_signers: list [optional]
                List of signer-ids to verify the signature against. Must be non-empty if 'signed=true'. Git only.

            layers: dict [optional]
                List of layers to append 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 | dict [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 disabled. This way it is possible to overwrite the inclusion of a layer in later loaded configuration files. To re-enable it, set it to nothing (null).

                    prio: integer [optional]
                        Include order priority, higher means earlier. The include priority is global, hence it is applied across all repositories.

                        Default: 0

                        Range: [-99, 99]

            patches: dict [optional]
                Patches to apply to the repository.

                <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]
        Overrides for specific configuration nodes. By that, only items that already exist are overridden. Note that the lock plugin uses overrides to manage pinning of commits. Manually added overrides can interfere with lock file generated by the plugin.

        repos: dict [optional]
            Maps to the top-level repos entry.

            <repo-id>: dict [optional]
                Maps to the <repo-id> entry.

                branch: string [optional]
                    Branch in which to find the overridden commit. Can be Null.

                commit: string [optional]
                    Pinned commit ID which overrides the commit of the corresponding repo. Can be Null.

                url: string [optional]
                    Alternative URL for the corresponding repo.

    bblayers_conf_header: dict [optional]
        Header to prepend 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]
        Header to prepend 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]
        Menu configuration, auto-generated by menu plugin. 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.

    artifacts: dict [optional]
        Artifacts which are expected to be present after executing the build (id / path pairs). Each key-value pair describes an identifier and a path relative to the kas build dir, whereby the path can contain wildcards like *. Unix-style globbing is applied to all paths. In case no artifact is found, the build is considered successful, if not stated otherwise by the used plugin and mode of operation.

        Note:
            There are no further semantics attached to the identifiers (yet). Both the author and the consumer of the artifacts node need to agree on the semantics.

    Example:

                artifacts:
                  disk-image: path/to/image.*.img
                  firmware: path/to/firmware.bin
                  swu: path/to/update.swu

    signers: dict [optional]
        Specification of the repository signature verification.

        This dict contains the public keys or certificates that are used to verify the authenticity of the repositories. In case of GPG keys, these are made available to the build environment as well by pointing the GNUPGHOME environment variable to the local keystore. A single signer configuration must not be split across multiple config files.

        <signer_id>: dict [optional]
            Pairs of name and location of a public key or certificate. The name is used to reference the entry in the repository configuration. For each signer, a unique identifier is required. The <signer_id> is used to reference the entry in the allowed_signers entries.

            type: enum [optional]
                Type of the cryptographic material.

                Default: gpg

                Supported values: gpg, ssh

            repo: string [optional]
                Repo <repo-id> which provides the public key or certificate file.

            path: string [optional]
                Path to the public key or certificate file, relative to the repo. Must be used together with 'repo'.

            fingerprint: string [optional]
                Fingerprint of the key or certificate (gpg: long-form, 40 hex digits, ssh: SHA256:...). If not provided, it is read from the file.

                GPG key fingerprint: The fingerprint can be obtained by running gpg --list-keys --with-fingerprint --keyid-format=long <KEYID>. The needed string is the 40-character fingerprint without spaces.

                SSH key fingerprint: The fingerprint can be obtained by running ssh-keygen -lf key.pub | awk '{print $2}'.

            gpg_keyserver: string [optional]
                GnuPG keyserver to use for key retrieval (if no local path is provided). The 'fingerprint' must be provided. GPG only.

    _source_dir: string [optional]
        Path to the top repo at time of invoking the plugin (auto-generated by the menu plugin). It must not be set manually and might only be defined in the top-level .config.yaml file.

    _source_dir_host: string [optional]
        Source directory of the config file on the host (auto-generated by kas menu plugin, when using kas-container). 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.

    buildtools: dict [optional]
        Provides variables to define which buildtools version should be fetched and where it is (or will be) installed. Both version and sha256sum should be set. The environment variable KAS_BUILDTOOLS_DIR can be used to set the directory where buildtools will be installed, otherwise the default path (i.e., KAS_BUILD_DIR/buildtools) will be used. If such directory already has buildtools installed, kas will check the Distro Version line in the version file, and if it doesn't match with version, the directory will be cleaned and kas will download buildtools according to version. After the download, kas will perform integrity validation by calculating the artifact's checksum and comparing it with sha256sum. As for the optional variables, they are meant to be used to support cases as: mirrors, changes in the installer's file name, and fetching unofficial (i.e., custom) buildtools. Finally, the environment-setup script will run before bitbake, so the whole buildtools environment will be available. wget is the host tool required for this feature. More information on how to install or generate buildtools can be found at: <https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#downloading-a-pre-built-buildtools-tarball>

        version: string
            Yocto Project version, as 5.0 (or even 5.0.8) for Scarthgap.

        sha256sum: string
            The installer's checksum, to perform integrity validation of the fetched artifact.

        base_url: string [optional]
            Base URL to fetch downloads from.

            Default: https://downloads.yoctoproject.org/releases/yocto

        filename: string [optional]
            Alternative name for the buildtools archive (.sh) to be downloaded. It will be combined with to base_url to form the whole download URL, if set. If not set, kas will combine the platform architecture and version to form the standard script filename: {arch}-buildtools-extended-nativesdk-standalone-{version}.sh

    Example:

                buildtools:
                  version: "5.2"
                  sha256sum: "6f69fba75c8f3142bb49558afa3ed5dd0723a3beda169b057a5238013623462d"

    And for unofficial (custom) sources:

                buildtools:
                  version: "1.0.0"
                  sha256sum: "a6f87e5865b63f2bc28c1f605bcef3d6680d46fa8c8616a388d4e8aa0b5c100e"
                  base_url: "https://downloads.mysources.com/yocto/buildtools/"
                  filename: "x86_64-buildtools-beta-testing-1.0.0.sh"

  Buildtools archive

kas expects the buildtools installer to be a shell script (i.e., as a standard Yocto SDK). Once executed, the resulting directory should contain the elements below:

    •   sysroots: the native and target sysroots, containing (among libraries and headers) the build system's requirements: Git, tar, Python and make.

    •   environment-setup-*: the environment setup script, sourced by kas, to setup variables such as PATH in such a way that it points to the directories in sysroots.

    •   version-*: the version file. Its second line contains a string as Distro Version: X.Y.Z, parsed to retrieve the version number.

The archive can contain other files, such as buildinfo, but they are not relevant for kas.

  Example project configurations

The following snippets show minimal but working project configurations for both OpenEmbedded and ISAR based distributions.

  OpenEmbedded

Poky

            header:
              version: 19

            # Optionally provide keys to verify signed repositories
            signers:
              YoctoBuildandRelease:
                fingerprint: 2AFB13F28FBBB0D1B9DAF63087EB3D32FB631AD9
                gpg_keyserver: keyserver.ubuntu.com

            machine: qemux86-64
            distro: poky

            target: zlib-native

            repos:
              poky:
                url: https://git.yoctoproject.org/poky.git
                # when specifying a tag, optionally provide a commit hash
                tag: yocto-5.1.1
                commit: 7e081bd98fdc5435e850d1df79a5e0f1e30293d0
                signed: true
                allowed_signers:
                  - YoctoBuildandRelease
                layers:
                  meta:
                  meta-poky:

oe-core (nodistro)

            header:
              version: 19

            # Optionally provide keys to verify signed repositories
            signers:
              YoctoBuildandRelease:
                fingerprint: 2AFB13F28FBBB0D1B9DAF63087EB3D32FB631AD9
                gpg_keyserver: keyserver.ubuntu.com

            machine: qemux86-64
            distro: nodistro

            target: zlib-native

            repos:
              bitbake:
                url: https://github.com/openembedded/bitbake.git
                tag: yocto-5.2.3
                commit: 710f98844ae30416bdf6a01b655df398b49574ec
                signed: true
                allowed_signers:
                  - YoctoBuildandRelease
                # this repo does not provide any layers
                layers: {}

              core:
                url: https://github.com/openembedded/openembedded-core.git
                tag: yocto-5.2.3
                commit: 347cb0861dde58613541ce692778f907943a60ea
                signed: true
                allowed_signers:
                  - YoctoBuildandRelease
                layers:
                  meta:

  ISAR

            header:
              version: 23

            build_system: isar-privileged

            machine: qemuamd64
            distro: debian-trixie

            target: mc:qemuamd64-trixie:cowsay

            repos:
              isar:
                url: https://github.com/ilbers/isar.git
                tag: v0.11
                commit: f8558fcf3ecf98e58853b82d89645bcedb24b853
                layers:
                  meta:
                  meta-isar:

SEE ALSO

kas-format-changelog(1)

KAS

Part of the kas(1) suite.

Author
Daniel Wagner, Jan Kiszka, Claudius Heine

Copyright
Siemens and contributors, 2017-2025