sysbuild_extensions

Sysbuild’s CMake extension commands.

This module defines the commands used to describe a sysbuild configuration: which images take part in the build, how they are configured, and in which order they are configured and flashed.

The commands documented below are available in the sysbuild.cmake file of any application or Zephyr module that participates in a sysbuild build.

Commands not documented here are used by sysbuild itself and may be removed, renamed, or re-purposed without prior notice.

sysbuild_get(<variable> IMAGE <image> [VAR <image-variable>] <KCONFIG|CACHE>)

Read a CMake cache variable or Kconfig setting from an image.

Sysbuild can only read an image once that image has been configured, for example from the post-CMake hook of a sysbuild module.

If VAR is provided, the name given as parameter will be looked up, but if VAR is not given, the <variable> name provided will be used both for lookup and value return.

The result will be returned in <variable>.

<variable>: Variable used for returning the value. Also used as lookup variable if VAR is not provided.
IMAGE <image>: Name of the image to read the variable from.
VAR <image-variable>: Name of the variable to look up.
KCONFIG: Flag indicating that a Kconfig setting should be fetched.
CACHE: Flag indicating that a CMake cache variable should be fetched.

Example usage:

# Look up PROJECT_NAME from the CMake cache of `my_sample` and return it
# in the local variable `PROJECT_NAME`.
sysbuild_get(PROJECT_NAME IMAGE my_sample CACHE)

# Same lookup, but returned in `my_sample_PROJECT_NAME`.
sysbuild_get(my_sample_PROJECT_NAME IMAGE my_sample VAR PROJECT_NAME CACHE)

# Look up the Kconfig setting CONFIG_FOO of `my_sample`.
sysbuild_get(my_sample_CONFIG_FOO IMAGE my_sample VAR CONFIG_FOO KCONFIG)

ExternalZephyrProject_Add(APPLICATION <name> SOURCE_DIR <dir> [BOARD <board> [BOARD_REVISION <revision>]] [APP_TYPE <MAIN|BOOTLOADER|FIRMWARE_LOADER>] [BUILD_ONLY <bool>] )

Include a Zephyr based build system into the multi-image build system.

APPLICATION <name>

Name of the application. The name will also be used for the build folder of the application.

SOURCE_DIR <dir>

Source directory of the application.

BOARD <board>

Use <board> for the application build instead of the user defined BOARD.

BOARD_REVISION <revision>

Use <revision> of <board> for the application. Only valid if BOARD is also supplied.

APP_TYPE <MAIN|BOOTLOADER|FIRMWARE_LOADER>

Application type.

MAIN indicates this application is the main application, and where user defined settings should be passed on as-is except for multi image build flags. For example, -DCONF_FILE=<files> will be passed on to the main application unmodified.

BOOTLOADER indicates this application is a bootloader.

FIRMWARE_LOADER indicates this application is a firmware loader image for MCUboot.

BUILD_ONLY <bool>

Mark the application as build-only. If <bool> evaluates to true, then this application will be excluded from flashing and debugging.

See Adding Zephyr applications to sysbuild for a worked example.

ExternalZephyrVariantProject_Add(APPLICATION <name> SOURCE_APP <name> [SNIPPET <snippet>] [EXTRA_DTC_OVERLAY_FILE <file>] [EXTRA_CONF_FILE <file>] [BUILD_ONLY <bool>] )

Duplicate an existing Zephyr based build system into the multi-image build system with a specified modification.

This will not create the extra build targets that ExternalZephyrProject_Add() adds, for example <app>_menuconfig.

Note

The variant image must have a CONF_FILE, EXTRA_CONF_FILE, EXTRA_DTC_OVERLAY_FILE or SNIPPET added to it, or it will be invalid and image configuration will result in a fatal error.

APPLICATION <name>: Name of the application. The name will also be used for the build folder of the application.
SOURCE_APP <name>: Name of the existing image to use for duplication.
SNIPPET <snippet>: List of default snippets to apply for the variant image.
EXTRA_DTC_OVERLAY_FILE <file>: List of default extra devicetree overlay files to apply for the variant image.
EXTRA_CONF_FILE <file>: List of default extra Kconfig fragments to apply for the variant image.
BUILD_ONLY <bool>: Mark the application as build-only. If <bool> evaluates to true, then this application will be excluded from flashing and debugging.

sysbuild_cache_set(VAR <variable> [APPEND [REMOVE_DUPLICATES]] <value>)

Set a sysbuild cache variable, which can then be accessed by images.

The result will be returned in <variable>.

VAR <variable>: Name of the variable in the CMake cache.
APPEND: If specified, append the supplied data to the existing value as a list.
REMOVE_DUPLICATES: If specified, remove duplicate entries contained within the list before saving to the cache.
<value>: Value to set or update.

Example usage:

# Add `battery` to the `ATTRIBUTES` list in the CMake cache, removing
# any duplicates from the list.
sysbuild_cache_set(VAR ATTRIBUTES APPEND REMOVE_DUPLICATES battery)

Setting Kconfig values on an image

The following commands add a Kconfig fragment line to <image>. They are the supported way for a sysbuild.cmake file to configure an image it has added.

The collected fragment is passed to the image as a forced input configuration, so it is applied last and takes precedence over the image’s own Kconfig fragments. See Kconfig namespacing for how these relate to SB_CONFIG_ options.

set_config_bool(<image> <setting> <value>): Set a boolean Kconfig option to y if <value> evaluates to true, and to n otherwise.

set_config_string(<image> <setting> <value>): Set a string Kconfig option to <value>.

set_config_int(<image> <setting> <value>)

Set an int or hex Kconfig option to <value>.

Example usage:

set_config_bool(${DEFAULT_IMAGE} CONFIG_BOOTLOADER_MCUBOOT y)
set_config_string(${DEFAULT_IMAGE} CONFIG_MCUBOOT_SIGNATURE_KEY_FILE "${keyfile}")
set_config_int(mcuboot CONFIG_LOG_MAX_LEVEL 2)

sysbuild_add_subdirectory(<source_dir> [<binary_dir>])

Add a subdirectory, and recursively process the sysbuild images it adds.

This command extends add_subdirectory with additional, recursive processing of the sysbuild images added via <source_dir>.

After exiting <source_dir>, this command will take every image added so far and include() its sysbuild.cmake file, if found. If more images get added at this stage, their sysbuild.cmake files will be included as well, and so on. This continues until all expected images have been added, before returning.

sysbuild_add_dependencies(<CONFIGURE | FLASH> <image> [<image-dependency> ...])

Make an image depend on other images in the configuration or flashing order.

Each image named <image-dependency> will be ordered before the image named <image>.

CONFIGURE: Add CMake configuration dependencies. This will determine the order in which images are configured.
FLASH: Add flashing dependencies. This will determine the order in which all images will appear in domains.yaml.

See Adding dependencies among Zephyr applications for a worked example.

sysbuild_images_order(<variable> <CONFIGURE | FLASH> IMAGES <images>)

Sort the provided <images> to satisfy the dependencies specified using sysbuild_add_dependencies().

The result will be returned in <variable>.