Sysbuild (System build)

Sysbuild is a higher-level build system that can be used to combine multiple other build systems together. It is a higher-level layer that combines one or more Zephyr build systems and optional additional build systems into a hierarchical build system.

For example, you can use sysbuild to build a Zephyr application together with the MCUboot bootloader, flash them both onto your device, and debug the results.

Sysbuild works by configuring and building at least a Zephyr application and, optionally, as many additional projects as you want. The additional projects can be either Zephyr applications or other types of builds you want to run.

Like Zephyr’s build system, sysbuild is written in CMake and uses Kconfig.

Definitions

The following are some key concepts used in this document:

Single-image build

When sysbuild is used to create and manage just one Zephyr application’s build system.

Multi-image build

When sysbuild is used to manage multiple build systems. The word “image” is used because your main goal is usually to generate the binaries of the firmware application images from each build system.

Domain

Every Zephyr CMake build system managed by sysbuild.

Multi-domain

When more than one Zephyr CMake build system (domain) is managed by sysbuild.

Architectural Overview

This figure is an overview of sysbuild’s inputs, outputs, and user interfaces:

The following are some key sysbuild features indicated in this figure:

• You can run sysbuild either with west build or directly via cmake.

• You can use sysbuild to generate application images from each build system, shown above as ELF, BIN, and HEX files.

• You can configure sysbuild or any of the build systems it manages using various configuration variables. These variables are namespaced so that sysbuild can direct them to the right build system. In some cases, such as the BOARD variable, these are shared among multiple build systems.

• Sysbuild itself is also configured using Kconfig. For example, you can instruct sysbuild to build the MCUboot bootloader, as well as to build and link your main Zephyr application as an MCUboot child image, using sysbuild’s Kconfig files.

• Sysbuild integrates with west’s Building, Flashing and Debugging commands. It does this by managing the Flash and debug runners, and specifically the runners.yaml files that each Zephyr build system will contain. These are packaged into a global view of how to flash and debug each build system in a domains.yaml file generated and managed by sysbuild.

Building with sysbuild

As mentioned above, you can run sysbuild via west build or cmake.

west buildcmake

Here is an example. For details, see Sysbuild (multi-domain builds) in the west build documentation.

west build -b reel_board --sysbuild samples/hello_world

Tip

To configure west build to use --sysbuild by default from now on, run:

west config build.sysbuild True

Since sysbuild supports both single- and multi-image builds, this lets you use sysbuild all the time, without worrying about what type of build you are running.

To turn this off, run this before generating your build system:

west config build.sysbuild False

To turn this off for just one west build command, run:

west build --no-sysbuild ...

Configuration namespacing

When building a single Zephyr application without sysbuild, all CMake cache settings and Kconfig build options given on the command line as -D<var>=<value> or -DCONFIG_<var>=<value> are handled by the Zephyr build system.

However, when sysbuild combines multiple Zephyr build systems, there could be Kconfig settings exclusive to sysbuild (and not used by any of the applications). To handle this, sysbuild has namespaces for configuration variables. You can use these namespaces to direct settings either to sysbuild itself or to a specific Zephyr application managed by sysbuild using the information in these sections.

The following example shows how to build Hello World with MCUboot enabled, applying to both images debug optimizations:

west buildcmake

west build -b reel_board --sysbuild samples/hello_world -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_DEBUG_OPTIMIZATIONS=y -Dmcuboot_DEBUG_OPTIMIZATIONS=y

See the following subsections for more information.

CMake variable namespacing

CMake variable settings can be passed to CMake using -D<var>=<value> on the command line. You can also set Kconfig options via CMake as -DCONFIG_<var>=<value> or -D<namespace>_CONFIG_<var>=<value>.

Since sysbuild is the entry point for the build system, and sysbuild is written in CMake, all CMake variables are first processed by sysbuild.

Sysbuild creates a namespace for each domain. The namespace prefix is the domain’s application name. See Adding Zephyr applications to sysbuild for more information.

To set the variable <var> in the namespace <namespace>, use this syntax:

-D<namespace>_<var>=<value>

For example, to set the CMake variable FOO in the my_sample application build system to the value BAR, run the following commands:

west buildcmake

west build --sysbuild ... -- -Dmy_sample_FOO=BAR

Kconfig namespacing

To set the sysbuild Kconfig option <var> to the value <value>, use this syntax:

-DSB_CONFIG_<var>=<value>

In the previous example, SB_CONFIG is the namespace prefix for sysbuild’s Kconfig options.

To set a Zephyr application’s Kconfig option instead, use this syntax:

-D<namespace>_CONFIG_<var>=<value>

In the previous example, <namespace> is the application name discussed above in CMake variable namespacing.

For example, to set the Kconfig option FOO in the my_sample application build system to the value BAR, run the following commands:

west buildcmake

west build --sysbuild ... -- -Dmy_sample_CONFIG_FOO=BAR

Tip

When no <namespace> is used, the Kconfig setting is passed to the main Zephyr application my_sample.

This means that passing -DCONFIG_<var>=<value> and -Dmy_sample_CONFIG_<var>=<value> are equivalent.

This allows you to build the same application with or without sysbuild using the same syntax for setting Kconfig values at CMake time. For example, the following commands will work in the same way:

west build -b <board> my_sample -- -DCONFIG_FOO=BAR

west build -b <board> --sysbuild my_sample -- -DCONFIG_FOO=BAR

Sysbuild flashing using west flash

You can use west flash to flash applications with sysbuild.

When invoking west flash on a build consisting of multiple images, each image is flashed in sequence. Extra arguments such as --runner jlink are passed to each invocation.

For more details, see Multi-domain flashing.

Sysbuild debugging using west debug

You can use west debug to debug the main application, whether you are using sysbuild or not. Just follow the existing west debug guide to debug the main sample.

To debug a different domain (Zephyr application), such as mcuboot, use the --domain argument, as follows:

west debug --domain mcuboot

For more details, see Multi-domain debugging.

Building a sample with MCUboot

Sysbuild supports MCUboot natively.

To build a sample like hello_world with MCUboot, enable MCUboot and build and flash the sample as follows:

west buildcmake

west build -b reel_board --sysbuild samples/hello_world -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y

This builds hello_world and mcuboot for the reel_board, and then flashes both the mcuboot and hello_world application images to the board.

More detailed information regarding the use of MCUboot with Zephyr can be found in the MCUboot with Zephyr documentation page on the MCUboot website.

Note

MCUBoot default configuration will perform a full chip erase when flashed. This can be controlled through the MCUBoot Kconfig option CONFIG_ZEPHYR_TRY_MASS_ERASE. If this option is enabled, then flashing only MCUBoot, for example using west flash --domain mcuboot, may erase the entire flash, including the main application image.

Sysbuild Kconfig file

You can set sysbuild’s Kconfig options for a single application using configuration files. By default, sysbuild looks for a configuration file named sysbuild.conf in the application top-level directory.

In the following example, there is a sysbuild.conf file that enables building and flashing with MCUboot whenever sysbuild is used:

<home>/application
├── CMakeLists.txt
├── prj.conf
└── sysbuild.conf

SB_CONFIG_BOOTLOADER_MCUBOOT=y

You can set a configuration file to use with the -DSB_CONF_FILE=<sysbuild-conf-file> CMake build setting.

For example, you can create sysbuild-mcuboot.conf and then specify this file when building with sysbuild, as follows:

west buildcmake

west build -b reel_board --sysbuild samples/hello_world -- -DSB_CONF_FILE=sysbuild-mcuboot.conf

Adding Zephyr applications to sysbuild

You can use the ExternalZephyrProject_Add() function to add Zephyr applications as sysbuild domains. Call this CMake function from your application’s sysbuild.cmake file, or any other CMake file you know will run as part sysbuild CMake invocation.

Targeting the same board

To include my_sample as another sysbuild domain, targeting the same board as the main image, use this example:

ExternalZephyrProject_Add(
  APPLICATION my_sample
  SOURCE_DIR <path-to>/my_sample
)

This could be useful, for example, if your board requires you to build and flash an SoC-specific bootloader along with your main application.

Targeting a different board

In sysbuild and Zephyr CMake build system a board may refer to:

• A physical board with a single core SoC.

• A specific core on a physical board with a multi-core SoC, such as nRF5340 DK.

• A specific SoC on a physical board with multiple SoCs, such as nRF9160 DK and nRF9160 DK - nRF52840.

If your main application, for example, is built for mps2_an521, and your helper application must target the mps2_an521_remote board (cpu1), add a CMake function call that is structured as follows:

ExternalZephyrProject_Add(
  APPLICATION my_sample
  SOURCE_DIR <path-to>/my_sample
  BOARD mps2_an521_remote
)

This could be useful, for example, if your main application requires another helper Zephyr application to be built and flashed alongside it, but the helper runs on another core in your SoC.

Targeting conditionally using Kconfig

You can control whether extra applications are included as sysbuild domains using Kconfig.

If the extra application image is specific to the board or an application, you can create two additional files: sysbuild.cmake and Kconfig.sysbuild.

For an application, this would look like this:

<home>/application
├── CMakeLists.txt
├── prj.conf
├── Kconfig.sysbuild
└── sysbuild.cmake

In the previous example, sysbuild.cmake would be structured as follows:

if(SB_CONFIG_SECOND_SAMPLE)
  ExternalZephyrProject_Add(
    APPLICATION second_sample
    SOURCE_DIR <path-to>/second_sample
  )
endif()

Kconfig.sysbuild would be structured as follows:

source "sysbuild/Kconfig"

config SECOND_SAMPLE
        bool "Second sample"
        default y

This will include second_sample by default, while still allowing you to disable it using the Kconfig option SECOND_SAMPLE.

For more information on setting sysbuild Kconfig options, see Kconfig namespacing.

Zephyr application configuration

When adding a Zephyr application to sysbuild, such as MCUboot, then the configuration files from the application (MCUboot) itself will be used.

When integrating multiple applications with each other, then it is often necessary to make adjustments to the configuration of extra images.

Sysbuild gives users the ability of creating Kconfig fragments or devicetree overlays that will be used together with the application’s default configuration. Sysbuild also allows users to change Application Configuration Directory in order to give users full control of an image’s configuration.

Zephyr application Kconfig fragment and devicetree overlay

In the folder of the main application, create a Kconfig fragment or a devicetree overlay under a sysbuild folder, where the name of the file is <image>.conf or <image>.overlay, for example if your main application includes my_sample then create a sysbuild/my_sample.conf file or a devicetree overlay sysbuild/my_sample.overlay.

A Kconfig fragment could look as:

# sysbuild/my_sample.conf
CONFIG_FOO=n

Zephyr application configuration directory

In the folder of the main application, create a new folder under sysbuild/<image>/. This folder will then be used as APPLICATION_CONFIG_DIR when building <image>. As an example, if your main application includes my_sample then create a sysbuild/my_sample/ folder and place any configuration files in there as you would normally do:

<home>/application
├── CMakeLists.txt
├── prj.conf
└── sysbuild
    └── my_sample
        ├── prj.conf
        ├── app.overlay
        └── boards
            ├── <board_A>.conf
            ├── <board_A>.overlay
            ├── <board_B>.conf
            └── <board_B>.overlay

All configuration files under the sysbuild/my_sample/ folder will now be used when my_sample is included in the build, and the default configuration files for my_sample will be ignored.

This give you full control on how images are configured when integrating those with application.

Adding non-Zephyr applications to sysbuild

You can include non-Zephyr applications in a multi-image build using the standard CMake module ExternalProject. Please refer to the CMake documentation for usage details.

When using ExternalProject, the non-Zephyr application will be built as part of the sysbuild build invocation, but west flash or west debug will not be aware of the application. Instead, you must manually flash and debug the application.

Extending sysbuild

Sysbuild can be extended by other modules to give it additional functionality or include other configuration or images, an example could be to add support for another bootloader or external signing method.

Modules can be extended by adding custom CMake or Kconfig files as normal modules do, this will cause the files to be included in each image that is part of a project. Alternatively, there are sysbuild-specific module extension files which can be used to include CMake and Kconfig files for the overall sysbuild image itself, this is where e.g. a custom image for a particular board or SoC can be added.