kas Configuration¶

Complete reference for the kas configuration layout used by ToloMEO integration projects: the role of each file, the integration contract exposed by meta-tolomeo's kas fragments, and the merge semantics that determine what ends up in bblayers.conf and local.conf.

For a guided walkthrough that builds this configuration from scratch, see Build Your Own BSP Layer.

File layout¶

<project-root>/
├── kas/
│   ├── base.yml                          # layer stack and global configuration
│   ├── common.yml                        # build paths and mirrors for local builds
│   ├── <feature>.yml                     # optional, self-contained setting groups
│   └── <machine>_<distro>_<image>.yml    # build targets
└── kas-ci/
    ├── common.yml                        # build paths and mirrors for CI builds
    ├── <machine>.yml                     # machine axis
    └── <distro>.yml                      # distribution axis

File roles¶

kas-ci/<distro>.yml carries no includes so that it can be appended to any machine fragment. With m machines and n distributions the CI matrix costs m + n files rather than m × n.

File naming¶

meta-tolomeo kas fragments¶

Each meta-tolomeo layer ships <layer>/kas/common.yml declaring what that layer needs. Include the fragments rather than restating their contents, so that dependency changes arrive with a commit bump:

header:
  version: 14
  includes:
    - repo: meta-tolomeo
      file: meta-tolomeo-app/kas/common.yml
    - repo: meta-tolomeo
      file: meta-tolomeo-bsp/kas/common.yml
    - repo: meta-tolomeo
      file: meta-tolomeo-distro/kas/common.yml

The repo: key resolves file: inside the named repository instead of the working repository.

meta-tolomeo-app/kas/common.yml¶

meta-tolomeo-bsp/kas/common.yml¶

meta-tolomeo-distro/kas/common.yml¶

meta-tolomeo-nxp/kas/common.yml¶

Include only for NXP i.MX targets. Requires the NXP vendor layers (meta-freescale, meta-freescale-distro, meta-imx, meta-arm) in your own repos:, and an ACCEPT_FSL_EULA = "1" config block.

meta-tolomeo-qemu/kas/common.yml¶

The meta-tolomeo-qemu layer provides the tolomeo-qemux86-64, tolomeo-qemuarm64 and tolomeo-qemuarm machines and the tolomeo-devel / tolomeo-prod reference distributions. Enable it in your meta-tolomeo layer list to keep a hardware-independent build available, and read its machine configurations as the worked example of the machine contract — see Machine Configuration. Do not derive your distributions from tolomeo-devel or tolomeo-prod; derive them from tolomeo.inc.

Feature fragments¶

kas/ also ships reusable feature fragments. The offline fragments below are special: unlike a plain kas/<feature>.yml (which carries only a local_conf_header block), they enable a layer and forward credentials.

kas/gitlab-auth.yml¶

Reusable GitLab credentials for fetching private DAVE repositories over HTTPS.

kas/offline.yml¶

Opt-in fragment enabling ToloMEO offline capabilities.

Append it to a target to build with offline support; the private tlm-bridge fetch uses the credentials from kas/gitlab-auth.yml. See Enable Offline Capabilities.

Merge semantics¶

Include resolution¶

header.includes entries are processed in order, depth-first, before the including file's own keys. A file therefore always wins over what it includes, and the last include wins over earlier ones.

local_conf_header blocks¶

local_conf_header is a mapping of block name to a literal chunk of local.conf text. Blocks are merged by name across all includes and concatenated into build/conf/local.conf.

• Reusing a block name replaces the earlier block entirely.
• A new block name adds content.
• Block ordering in the generated file is not guaranteed; never write a block that depends on another block's position.

Prefix your own block names with your project slug (common-acme, common-acme-ci) so they cannot collide with meta-tolomeo's. Reuse a meta-tolomeo block name only when you intend to replace it — buildinfo is the usual case.

repos merging¶

Repository entries merge by key. A later file may add layers to a repository declared earlier without restating its url, branch or commit:

# kas/base.yml
repos:
  meta-tolomeo:
    url: https://gitlab.com/DAVEEmbeddedSystems/public/tolomeo-public-projects/edge/tolomeo-edge/meta-tolomeo
    branch: scarthgap
    commit: <sha>
    path: sources/meta-tolomeo
    layers:
      meta-tolomeo-app:

# kas/common.yml — adds one more layer from the same repository
repos:
  meta-tolomeo:
    layers:
      meta-tolomeo-qemu:

env passthrough¶

env:
  SWUPDATE_KEYDIR: null

A null value declares the variable as forwarded from the environment into BitBake's datastore with no default. A non-null value supplies a default that the environment can still override. This is how CI injects secrets without writing them into any tracked file.

Repository declaration¶

* for fetched repositories; not applicable to the working repository.

Pinning policy: always give both a branch (or tag) and a commit. The commit determines what is built; the branch or tag records where it came from and gives a bump a target. A branch without a commit makes builds non-reproducible.

bblayers_conf_header¶

bblayers_conf_header:
  env: |
    BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"

BSPDIR resolves to the project root. meta-tolomeo uses it to default UBOOT_SIGN_KEYDIR and SWUPDATE_KEYDIR to ${BSPDIR}/keys, so a keys symlink or directory at the project root is all that is needed to supply signing material.

Signature handling with mirrors¶

BB_HASHSERVE = ""
BB_SIGNATURE_HANDLER = "OEBasicHash"

These two settings are a pair, and they are a precondition for the sstate mirrors being useful. The default equivalence-hash handler derives task signatures from a hash-equivalence server's local history, which cannot match the signatures a shared mirror was populated with. OEBasicHash makes signatures a pure function of the metadata, producing cache hits instead of misses.

Commands¶

Use kas dump --resolve-refs to validate a new configuration before starting a build: confirm that every repository has a concrete commit, that the expected layers are present, and that your local_conf_header blocks appear once each.