Sysbuild configuration
This section will explain how to configure Sysbuild within an application. While all of this information should also be documented in the Sysbuild Documentation, we will take a step-by-step approach in this lesson to make it easier to understand.
Sysbuild Kconfig
If you have gotten this far into DevAcademy, you are used to setting Kconfig options in prj.conf (aka: application configuration file) for your project. Sysbuild uses the same concept but has its own set of Kconfig symbols. Sysbuild Kconfig symbols differ from application Kconfig options by the SB_ prefix, e.g. SB_CONFIG_..., and they are set in the file named sysbuild.conf in the application.
For example, the image below shows a Sysbuild Kconfig symbol SB_CONFIG_BOOTLOADER_MCUBOOT which adds the MCUboot bootloader as an extra image (covered in Exercise 1 of this lesson and in-depth in Lesson 9).
A list of most of the available Sysbuild Kconfig options is available in the Migrating from multi-image builds to sysbuild guide. Alternatively, run “west build -t sysbuild_menuconfig” from a terminal, or use the nRF Kconfig GUI from “build (sysbuild)” in the VS Code Extension.
From the image below, first click 1, and then click 2. Then you can see from 3 that this is an nRF Kconfig GUI for Sysbuild image configuration.
Sysbuild configuration folder
The project folder is the “home folder” for Sysbuild. We will call this the “main image” for the rest of this lesson, but this is not a name Sysbuild uses for anything. The main image folder is typically the project you run. This can be your Hello World, Peripheral LBS, or Matter door lock. In other words, the main image is likely what your project already is.
Sysbuild configuration goes into the same folder as the main image. But keep in mind that even though Sysbuild configuration is in the main image folder, it is not part of the main image configuration.
Sysbuild configuration files
Here is a list of configuration files and what they do:
| File path | Explanation | Project equivalent (for comparison) |
<main_image>/sysbuild.conf | Setting Sysbuild Kconfig options for the project | prj.conf |
< | Adding custom Sysbuild Kconfig symbols | Kconfig |
< | Managing CMake for Sysbuild | CMakeLists.txt |
< | Overlay for images | N/A |
Exercises in this lesson will cover “sysbuild.conf“, “sysbuild.cmake“, and “<“. “main_image>/sysbuild/Kconfig.sysbuild” will not be covered here. See the Sysbuild documentation and the sample below for how to use that.
See the “zephyr/samples/sysbuild/hello_world” Sysbuild Hello World sample for an example on how a folder with Sysbuild configurations may look:
Image names
Each image has an image name. For the main image, this will be the application folder name: For example, the Hello World image name will be hello_world, and the MCUboot image name will be “mcuboot“. The easiest way to see image names is to look in the build folder. The hello world build folder with MCUboot will look like this:
Image overlays and Kconfig fragments
Of the above Sysbuild configuration, the “main_image/sysbuild/” folder is the second most used after sysbuild.conf. This is where configurations for images are added.
For example, if you want to turn off logging in MCUboot or the nRF5340 network core, you would use this.
The “sysbuild/” folder expects the following possible files. The standard approach involves using overlaying, which builds on the existing extra image configuration. Alternatively, it is possible to overwrite the entire extra image configuration using the overwriting method. This is also explained in depth in our technical documentation.
Overlaying :
Purpose: To customize the configuration of an extra image by overlaying existing configration.
Location: Create a Kconfig fragment or devicetree overlay under sysbuild/<image_name>.conf or sysbuild/<image_name>.overlay.
| File path | Explanation | Example |
< | Kconfig fragment for image_name | < |
< | Overlay for image_name DTS | < |
Overwriting:
| File path | Explanation | Example |
< | Overwrites image_name Kconfig base configuration. This file must exist for any of the following files to be used. | < |
< | Overwrites image_name DTS base configuration. | <app.overlay |
< | Board Kconfig fragment for image_name. | < |
< | Board overlay for image_name DTS | < |
For more examples, see Sysbuild Migration guide -> Examples for MCUboot.
Multi-Image build (predecessor to Sysbuild)
Important
The “Multi-image build” feature is only relevant to old nRF Connect SDK versions. It will be completely deprecated in v3.0.0.
“Multi-image builds” is an nRF Connect SDK-specific feature for building multiple images that is the predecessor to Sysbuild. If you use Sysbuild, you do not use this.
This section is for users who are still using old versions of the nRF Connect SDK and want to learn about Multi-image builds.
To explain multi-image builds, let’s first have a look at how a program for an nRF chip would look without any framework for building multiple images. In this case, we first build the bootloader and then the application. Both are built separately, without any knowledge of each other. It is up to the developer to make sure that the bootloader and application agree on where in flash they are stored. We can call this Partition Information. After the images have been built, the output file (typically hex) from each build is written to the nRF chip separately. Here is a figure to illustrate the process:
It is possible to use the above method in the nRF Connect SDK, but it is not the default. Instead, we use our Multi-Image Build system to make the build system handle the building of multiple images.
In multi-image builds, an application is built as the main image, and all other images are added as child images to this main image.
Here is a simplified figure which shows how the multi-image build system can be illustrated:
We will now cover the main features of multi-image builds in the following subsections.
Building images in order and choosing the default child image
When the main application is built, the multi-image build system will automatically build all child images in the correct order. As an example, if we add CONFIG_BOOTLOADER_MCUBOOT=y to the Zephyr Hello World sample, this will enable multi-image builds. (We will have a closer look at this in upcoming exercises) From the resulting build log, observe that a child image is built in the below figure, marked as (1):
While it is possible to add custom child images to applications, a few types of child images make up the majority of use-cases. These are Bootloaders and network core images. In the nRF Connect SDK, we have a set of default samples which can be used as child images for these. When enabling certain features, the multi-image build system will be enabled, and automatically choose a fitting image for that based on configurations in the main application, as follows:
- CONFIG_SECURE_BOOT: Adds the Nordic Secure Immutable Bootloader sample as child image.
- CONFIG_BOOTLOADER_MCUBOOT: Adds the MCUboot application as child image.
- nRF5340: Supported Protocols gives an overview over configurations add which samples as child images, when building for the nRF5340.
Configuring child images
If Child images are often built from samples in the nRF Connect SDK, and we do not recommend making changes to the nRF Connect SDK source, then how can we configure the child images?
Multi-image builds gives us the possibility for configuring Image-specific variables, either by overlaying or changing existing child image configurations. There are two main ways to configure child images: Either using CMake arguments, or by using a predefined folder structure and configuration files.
To use CMake arguments, we can either overlay individual Kconfig options using -D<child_image>_CONFIG_WHATEVER=y, for example: -Dmcuboot_CONFIG_LOG_DEFAULT_LEVEL=3 . An illistration is shown below:
We can also overlay using files using CMake arguments. This is done by using -D<child_image>_EXTRA_CONF_FILE or -D<child_image>_DTC_OVERLAY_FILE. Or to overwrite Kconfig, we can use -D<child_image>_CONF_FILE.
The alternative is to use a folder structure to add files to the project. This is the method we recommend, and the method most of our examples use to configure child images. These files must be located inside a directory named child_image, and are named after the child image. This is typically child_image/mcuboot.conf or child_image/mcuboot/prj.conf, but a full list can be found at Multi-image builds: Permanent configuration changes to child images:
Here is an example of how a simple project with MCUboot overlays would look:
Generate output files
The multi-image build system will also generate output files, used for programming or DFU of the nRF chip. When we use the “Flash” function in the VS Code Extension for a single image build, build/zephyr/zephyr.hex is programmed to the nRF chip. For multi-image builds, build/zephyr/merged.hex is used instead. A list over output build files generated by multi-image builds can be found under Multi-image builds: What image files are. A more comprehensive list over generated output build in the nRF Connect SDK can be found in our Build and configuration system docs. The multi-image build system will also generate different output build files for different cores when relevant.
Partitioning
Multi-image builds use the Partition Manager for partitioning.
