Skip to content

Artifacts Collection

The artifacts_collector_* classes copy selected build outputs into a versioned tree under ARTIFACTS_BASE_DIR.

Base Directory and Version

Each class copies outputs from the Yocto deploy directory to a versioned directory tree outside the build folder. 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 comes from the buildinfo block in the local_conf_header section of the kas configuration (for example kas/common.yml):

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

Note

The buildinfo block assigns BUILD_VERSION with =, so a shell environment variable does not override it.

Five classes cover the main recipe types. Each class activates only when the recipe produces the expected task (for example 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

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

All ToloMEO image recipes inherit this class through include/tolomeo-image-common.inc. An image recipe that does not include that file needs its own inherit statement.

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

artifacts_collector_swupdate collects the generated .swu archives in SWUpdate package recipes.

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

Building from Collected Images

swupdate_import_images builds the .swu package from images already collected under an artifacts tree, instead of building DEFAULT_IMAGE_DEPENDS. The CI package stage sets SWUPDATE_EXTERNAL_IMAGES_DIR to the whole artifacts/ tree. do_import_images links each file in SWUPDATE_IMAGES into DEPLOY_DIR_IMAGE, looked up in this order:

  1. <SWUPDATE_EXTERNAL_IMAGES_DIR>/<MACHINE>/<SWUPDATE_BASE_IMAGE>/
  2. The whole SWUPDATE_EXTERNAL_IMAGES_DIR tree, for files the base image does not collect

A file name found more than once in the same scope stops the build.

Variable Default Description
SWUPDATE_EXTERNAL_IMAGES_DIR — Absolute path of the artifacts tree to import from; unset builds the images as usual
SWUPDATE_BASE_IMAGE — Base image recipe name; required when SWUPDATE_EXTERNAL_IMAGES_DIR is set
DEFAULT_IMAGE_DEPENDS — Image recipes built when SWUPDATE_EXTERNAL_IMAGES_DIR is unset

Delta Update Recipes

artifacts_collector_delta collects the generated .swu archive of a delta update recipe 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

artifacts_collector_component collects the outputs of .bbappend files or standalone recipes that produce deployable components such as a kernel or bootloader, 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

artifacts_collector_sdk serves 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. Setting the variable explicitly avoids the 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

See also