kas Configuration¶
A ToloMEO integration project's kas configuration is a set of files with fixed roles that include meta-tolomeo's per-layer fragments.
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¶
| File | Includes | Declares | Never declares |
|---|---|---|---|
kas/base.yml |
meta-tolomeo layer fragments | repos:, bblayers_conf_header, machine-independent local_conf_header blocks |
machine, distro, target, paths |
kas/common.yml |
kas/base.yml, feature files |
TMPDIR, DL_DIR, SSTATE_DIR, SSTATE_MIRRORS, signature handler |
machine, distro, target |
kas/<feature>.yml |
nothing | one cohesive local_conf_header block |
repos:, targets |
kas/<target>.yml |
kas/common.yml |
machine, distro, target — nothing else |
anything else |
kas-ci/common.yml |
kas/base.yml, feature files |
CI paths, SSTATE_MIRRORS, PREMIRRORS, CI_JOB_TOKEN SRC_URI overrides |
machine, distro, target |
kas-ci/<machine>.yml |
kas-ci/common.yml |
machine |
distro, target |
kas-ci/<distro>.yml |
nothing | distro |
everything else |
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¶
| Pattern | Use | Example |
|---|---|---|
<machine>_<distro>_<image>.yml |
an image build | acme-mx8mp-prod_acme-prod_acme-image-prod.yml |
<machine>_<purpose>.yml |
a non-image target; distribution is implied | acme-mx8mp-prod_imgen-update-full.yml |
<feature>.yml |
a reusable settings group | secure-boot.yml, mfg-settings.yml |
kas-ci/<machine>.yml |
CI machine axis | kas-ci/acme-mx8mp-prod.yml |
kas-ci/<distro>.yml |
CI distribution axis | kas-ci/acme-prod.yml |
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¶
| Adds | Value |
|---|---|
| Repositories | none |
| Config blocks | none |
env passthrough |
SYS_USER_PASSWORD_ROOT, SYS_USER_PASSWORD_ADMIN |
meta-tolomeo-bsp/kas/common.yml¶
| Adds | Value |
|---|---|
| Repositories | none |
| Config block | common-secure-boot — UBOOT_SIGN_KEYDIR ?= "${BSPDIR}/keys", UBOOT_SIGN_KEYNAME ?= "fitImage-sign" |
env passthrough |
UBOOT_SIGN_KEYDIR, UBOOT_SIGN_KEYNAME |
meta-tolomeo-distro/kas/common.yml¶
| Adds | Value |
|---|---|
| Repositories | meta-lts-mixins-go, meta-lts-mixins-rust, meta-security (with meta-hardening, meta-integrity), meta-swupdate, meta-vulnscout, meta-virtualization |
| Config block | common-swupdate — SWUPDATE_KEYDIR ?= "${BSPDIR}/keys", SWUPDATE_SIGN_KEYNAME ?= "swupdate-sign", SWUPDATE_ENC_KEYNAME ?= "swupdate-enc" |
| Config block | common-cve-nvd-update — NVDCVE_API_KEY, CVE_DB_UPDATE_INTERVAL, CVE_DB_INCR_UPDATE_AGE_THRES, CVE_DB_BACKUP_URL |
env passthrough |
SWUPDATE_KEYDIR, SWUPDATE_SIGN_KEYNAME, SWUPDATE_ENC_KEYNAME, SWUPDATE_BASE_IMAGE, SWUPDATE_EXTERNAL_IMAGES_DIR, NVDCVE_API_KEY, CVE_DB_UPDATE_INTERVAL, CVE_DB_INCR_UPDATE_AGE_THRES, CVE_DB_BACKUP_URL, BUILD_VERSION, FIRMWARE_NAME, VERSION_FROM, VERSION_TO |
meta-tolomeo-nxp/kas/common.yml¶
Include only for NXP i.MX targets. It 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.
| Adds | Value |
|---|---|
| Config block | common-secure-boot-nxp — SIG_DATA_PATH ?= "${BSPDIR}/keys/secure-boot", SIG_TOOL_PATH ?= "${BSPDIR}/venv/bin" |
meta-tolomeo-qemu/kas/common.yml¶
| Adds | Value |
|---|---|
| Config block | buildinfo — reference FIRMWARE_NAME, BUILD_VERSION and SECURITY_PATCH_LEVEL |
The meta-tolomeo-qemu layer provides the tolomeo-qemux86-64, tolomeo-qemuarm64 and tolomeo-qemuarm machines
and the tolomeo-devel / tolomeo-prod reference distributions. Enabling it in your meta-tolomeo layer list keeps a
hardware-independent build available, and its machine configurations are the worked example of the machine contract; see
Machine Configuration. A derived distribution requires conf/distro/include/tolomeo.inc
rather than tolomeo-devel or tolomeo-prod.
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.
| Adds | Value |
|---|---|
env passthrough |
TLM_GITLAB_USER (default oauth2), TLM_GITLAB_TOKEN (no default) |
kas/offline.yml¶
Opt-in fragment enabling ToloMEO offline capabilities.
| Adds | Value |
|---|---|
| Includes | kas/gitlab-auth.yml |
| Repositories | enables the meta-tolomeo-offline layer in the meta-tolomeo repo |
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.
| Include form | Resolved against |
|---|---|
- kas/base.yml |
the working repository |
- repo: <name>file: <path> |
repository <name> in repos: |
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.
- kas 4.x writes the blocks in sorted order of their names, each after a
# <name>comment line.
Block names carry the project slug (common-acme, common-acme-ci) so they cannot collide with meta-tolomeo's. Reusing
a meta-tolomeo block name replaces 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¶
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¶
| Key | Required | Notes |
|---|---|---|
url |
no | Omit for the working repository — the project you are building from |
branch |
yes* | Documents the upstream line; use with commit |
tag |
no | Alternative to branch for vendor releases; use with commit |
commit |
yes* | The pin that makes the build reproducible |
path |
yes* | Conventionally sources/<name> |
layers |
no | Enables exactly the listed sub-layers. Omit to enable the repository root as a single layer |
* 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¶
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¶
| Command | Effect |
|---|---|
kas build <file> |
Check out repositories, generate the build configuration, build |
kas checkout <file> |
Check out and generate configuration only, no build |
kas dump <file> |
Print the merged configuration; nothing is fetched or built |
kas dump --resolve-refs <file> |
As above, with every ref resolved to a concrete commit |
kas shell <file> -c '<cmd>' |
Run a command inside the configured BitBake environment |
kas build <a>.yml:<b>.yml |
Merge multiple configuration files, left to right |
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.
See also
- Build Your Own BSP Layer — wire kas in an integration project
- Machine Configuration — the machine contract kas selects
- Enable Offline Capabilities — build with
kas/offline.yml