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.
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:
| 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.
File Selection¶
The class defaults to collecting all files matching *rootfs.swu. Override
ARTIFACTS_PATTERNS to select a specific archive:
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:
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:
<SWUPDATE_EXTERNAL_IMAGES_DIR>/<MACHINE>/<SWUPDATE_BASE_IMAGE>/- The whole
SWUPDATE_EXTERNAL_IMAGES_DIRtree, 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.
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:
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.
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.
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:
| 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:
Example — disable all image artifact collection globally in local.conf:
To redirect artifacts to a different directory without disabling collection, override
ARTIFACTS_BASE_DIR:
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
- Generate a Delta Update — delta artifacts collected here
- Update Mechanism — image and package formats