Build Artifact Collection¶

Automatically copying build outputs (images, SWUpdate packages, SDK toolchains, and standalone components) to a versioned archive directory outside the Yocto build tree.

Table of Contents¶

Overview
Image Recipes
SWUpdate Recipes
Delta Update Recipes
Component Recipes
SDK Artifacts
Disabling Collection
Artifact Structure

Overview¶

The artifact collection system copies selected build outputs from the Yocto deploy directory into a versioned directory tree outside the build folder. This makes it easy to archive, share, or inspect build results without navigating the Yocto tmp directory.

All collected artifacts land under a configurable base directory:

Variable	Default	Description
`ARTIFACTS_BASE_DIR`	`${BSPDIR}/artifacts`	Root directory for all collected artifacts
`BUILD_VERSION`	`unknown-version`	Version label used as a subdirectory name

BUILD_VERSION is set in the kas configuration file. Edit the local_conf_header section of your kas config (e.g. kas/common.yml) to match your release version:

local_conf_header:
  buildinfo: |-
    FIRMWARE_NAME = "TVD-embedded-firmware"
    BUILD_VERSION = "1.2.1+26.03"

Note: Set BUILD_VERSION in the kas configuration file, not as a shell environment variable. Setting it at the shell level does not guarantee that it is consistently applied across all recipes and build steps.

Four specialized classes cover the main recipe types. Each class activates only when the recipe actually produces the expected task (e.g. do_image_complete, do_swuimage, do_populate_sdk, do_deploy), so inheriting a class in a recipe that does not run the relevant task is harmless.

Image Recipes¶

Use artifacts_collector_image in image recipes to collect root filesystem images, bootloader binaries, and related deploy-time outputs.

All ToloMEO image recipes inherit this class automatically via include/tolomeo-image-common.inc. No additional inherit statement is needed unless you are writing an image recipe that does not include that file.

inherit artifacts_collector_image

File Selection¶

If ARTIFACTS_PATTERNS is not set, the class applies a built-in default pattern that matches the root filesystem, Linux kernel images, device tree blobs, bootloader binaries, and other common deploy outputs. Override it in your recipe or machine configuration to select different files:

ARTIFACTS_PATTERNS = "${IMAGE_BASENAME}-${MACHINE}.rootfs.ext4.gz \
                      ${IMAGE_BASENAME}-${MACHINE}.rootfs.qemuboot.conf \
                      u-boot.bin \
                      u-boot-initial-env \
                      "

Machine-specific file selections can use BitBake overrides:

ARTIFACTS_PATTERNS:append:qemux86-64 = " bzImage"
ARTIFACTS_PATTERNS:append:qemuarm64 = " Image"

Variable	Default	Description
`ARTIFACTS_PATTERNS`	`${IMAGE_BASENAME}-${MACHINE}.rootfs. *fitImage ...`	Glob patterns for files to collect
`ARTIFACTS_IMAGE_COLLECT`	`1`	Set to `0` to disable collection entirely

CycloneDX Integration¶

If the image inherits cyclonedx_assemble, the collector also copies the CycloneDX export directory (CYCLONEDX_EXPORT_DIR) into a cyclonedx/ subdirectory alongside the other artifacts. No additional configuration is required.

SWUpdate Recipes¶

Use artifacts_collector_swupdate in SWUpdate package recipes to collect the generated .swu archives.

inherit artifacts_collector_swupdate

File Selection¶

The class defaults to collecting all files matching *rootfs.swu. Override ARTIFACTS_PATTERNS to select a specific archive:

ARTIFACTS_PATTERNS = "${PN}-${MACHINE}.rootfs.swu"

Linking to the Base Image¶

The SWUpdate collector reads the artifact metadata written by the base image build to determine the correct output subdirectory. Set IMAGE_DEPENDS to the name of the image recipe the .swu package targets:

IMAGE_DEPENDS = "image-prod"

When metadata is found, the .swu archive is placed under the same versioned directory as the base image artifacts, inside an updates/<recipe-name>/ subfolder. If no metadata is found the collector falls back to IMAGE_BASENAME and emits a warning.

Variable	Default	Description
`ARTIFACTS_PATTERNS`	`*rootfs.swu`	Glob patterns for files to collect
`IMAGE_DEPENDS`	—	Base image recipe name; used for build ordering and subdir naming
`ARTIFACTS_SWUPDATE_COLLECT`	`1`	Set to `0` to disable collection entirely

Delta Update Recipes¶

Use artifacts_collector_delta in delta update recipes to collect the generated .swu archive into a version-pair subdirectory.

inherit artifacts_collector_delta

Required Configuration¶

Three variables are required. The class is silently disabled if any of them is unset:

DELTA_IMAGE_NAME = "image-prod"   # base image name; determines the output subdirectory
VERSION_FROM     = "1.0.0"        # version being updated from
VERSION_TO       = "1.1.0"        # version being updated to

The class activates only when the recipe defines a do_swuimage task.

File Selection¶

The class defaults to collecting all files matching *.swu. Override ARTIFACTS_PATTERNS to include additional delta artifacts such as binary patches or metadata files:

ARTIFACTS_PATTERNS = "*.swu *.delta *.delta.gz delta-info.json"

Collected files land under: <ARTIFACTS_BASE_DIR>/<machine>/<DELTA_IMAGE_NAME>/<VERSION_TO>/updates/from_<VERSION_FROM>/

Variable	Default	Description
`DELTA_IMAGE_NAME`	—	Base image name; used as the output subdirectory; required
`VERSION_FROM`	—	Source version being patched from; required
`VERSION_TO`	—	Target version being patched to; required
`ARTIFACTS_PATTERNS`	`*.swu`	Glob patterns for files to collect
`ARTIFACTS_DELTA_COLLECT`	`1`	Set to `0` to disable collection entirely

Component Recipes¶

Use artifacts_collector_component in .bbappend files or standalone recipes that produce deployable components such as a kernel or bootloader, and whose outputs should be collected independently from the main image build.

inherit artifacts_collector_component

Required Configuration¶

Unlike the image and SWUpdate classes, the component class does not derive defaults for either the target subdirectory or the file selection. Both variables must be set explicitly:

# Subdirectory name under ARTIFACTS_BASE_DIR/<machine>/
ARTIFACTS_IMAGE_BASENAME = "${PN}"

# Files to collect from DEPLOY_DIR_IMAGE
ARTIFACTS_PATTERNS = "bzImage"

Machine-specific selections work as expected:

ARTIFACTS_IMAGE_BASENAME:qemuall = "${PN}"
ARTIFACTS_PATTERNS:qemux86-64    = "bzImage"
ARTIFACTS_PATTERNS:qemuarm64     = "Image"
ARTIFACTS_PATTERNS:qemuarm       = "zImage"

The class activates only when the recipe defines a do_deploy task. If ARTIFACTS_IMAGE_BASENAME is not set the collection task is silently skipped.

Variable	Default	Description
`ARTIFACTS_IMAGE_BASENAME`	—	Target subdirectory under `<machine>/`; required
`ARTIFACTS_PATTERNS`	—	Glob patterns for files to collect; required
`ARTIFACTS_COMPONENT_COLLECT`	`1`	Set to `0` to disable collection entirely

SDK Artifacts¶

Use artifacts_collector_sdk in image recipes that also build an SDK toolchain via do_populate_sdk. The class runs as a post-function of the SDK build and collects the toolchain installer into a sdk/ subdirectory alongside the image artifacts.

inherit artifacts_collector_sdk

This class is typically combined with artifacts_collector_image on the same recipe:

inherit core-image
inherit artifacts_collector_sdk
require include/tolomeo-image-common.inc  # pulls in artifacts_collector_image

File Selection¶

If ARTIFACTS_SDK_PATTERNS is not set, the class derives a default pattern from TOOLCHAIN_OUTPUTNAME. If TOOLCHAIN_OUTPUTNAME is also unset a warning is emitted and collection will fail at build time. Set the variable explicitly to avoid ambiguity:

ARTIFACTS_SDK_PATTERNS = "${TOOLCHAIN_OUTPUTNAME}*"

Variable	Default	Description
`ARTIFACTS_SDK_PATTERNS`	`${TOOLCHAIN_OUTPUTNAME}*`	Glob patterns for SDK files to collect
`ARTIFACTS_SDK_COLLECT`	`1`	Set to `0` to disable collection entirely

Note: ARTIFACTS_SDK_PATTERNS is a separate variable from ARTIFACTS_PATTERNS so that SDK and image file selections can be controlled independently on the same recipe.

Disabling Collection¶

Each class exposes a dedicated flag to disable artifact collection without removing the inherit statement. Set the flag to 0 in your recipe, machine configuration, or local.conf:

Class	Disable flag
`artifacts_collector_image`	`ARTIFACTS_IMAGE_COLLECT`
`artifacts_collector_sdk`	`ARTIFACTS_SDK_COLLECT`
`artifacts_collector_swupdate`	`ARTIFACTS_SWUPDATE_COLLECT`
`artifacts_collector_delta`	`ARTIFACTS_DELTA_COLLECT`
`artifacts_collector_component`	`ARTIFACTS_COMPONENT_COLLECT`

Example — disable SDK collection for a specific machine:

ARTIFACTS_SDK_COLLECT:qemux86-64 = "0"

Example — disable all image artifact collection globally in local.conf:

ARTIFACTS_IMAGE_COLLECT = "0"

To redirect artifacts to a different directory without disabling collection, override ARTIFACTS_BASE_DIR:

ARTIFACTS_BASE_DIR = "/mnt/release-storage/artifacts"

Artifact Structure¶

All artifacts are organized by machine, image name, and build version under ARTIFACTS_BASE_DIR. A build-info.txt file is written alongside the collected files in each directory, recording the build timestamp, machine, image name, version, and file count.

artifacts/
└── tolomeo-qemux86-64/
    ├── image-devel/
    │   └── 1.2.1+26.03/
    │       ├── build-info.txt
    │       ├── image-devel-tolomeo-qemux86-64.rootfs.ext4.gz
    │       ├── image-devel-tolomeo-qemux86-64.rootfs.qemuboot.conf
    │       ├── bzImage
    │       ├── u-boot.bin
    │       ├── cyclonedx/                          # present when cyclonedx_assemble is active
    │       │   ├── bom.json
    │       │   ├── vex.json
    │       │   └── summary.json
    │       ├── sdk/                                # present when artifacts_collector_sdk is inherited
    │       │   ├── build-info.txt
    │       │   └── x86_64-buildtools-extended-nativesdk-standalone-*.sh
    │       └── updates/
    │           ├── imgen-update-full/              # one subdirectory per SWUpdate recipe
    │           │   ├── build-info.txt
    │           │   └── imgen-update-full-tolomeo-qemux86-64.rootfs.swu
    │           └── from_1.0.0/                     # delta recipe: from_<VERSION_FROM>
    │               ├── build-info.txt
    │               └── imgen-update-delta-tolomeo-qemux86-64.rootfs.swu
    └── linux-yocto/                                # component recipe with ARTIFACTS_IMAGE_BASENAME = "${PN}"
        └── 1.2.1+26.03/
            ├── build-info.txt
            └── bzImage