Build and configuration system
The nRF Connect SDK build and configuration system is based on the one from Zephyr, with some additions.
Zephyr’s build and configuration system
Zephyr’s build and configuration system uses the following building blocks as a foundation:
CMake, the cross-platform build system generator
Kconfig, a powerful configuration system also used in the Linux kernel
Devicetree, a hardware description language that is used to describe the hardware that the nRF Connect SDK is to run on
Since the build and configuration system used by the nRF Connect SDK comes from Zephyr, references to the original Zephyr documentation are provided here in order to avoid duplication. See the following links for information about the different building blocks mentioned above:
Application Development is a complete guide to application development with Zephyr, including the build and configuration system.
Build System (CMake) describes in-depth the usage of CMake for Zephyr-based applications.
Kconfig Configuration contains a guide for Kconfig usage in applications.
Set devicetree overlays explains how to use devicetree and its overlays to customize an application’s devicetree.
Board Porting Guide is a complete guide to porting Zephyr to your own board.
nRF Connect SDK additions
The nRF Connect SDK adds some functionality on top of the Zephyr build and configuration system. Those additions are automatically included into the Zephyr build system using a Zephyr Build Configuration CMake package.
You must be aware of these additions when you start writing your own applications based on this SDK.
The Kconfig option
CONFIG_WARN_EXPERIMENTAL
is enabled by default. It gives warnings at CMake configure time if any experimental feature is enabled.For example, when building a sample that enables
CONFIG_BT_EXT_ADV
, the following warning is printed at CMake configure time:warning: Experimental symbol BT_EXT_ADV is enabled.
For more information, see Software maturity levels.
The nRF Connect SDK provides an additional
boilerplate.cmake
that is automatically included when using the Zephyr CMake package in theCMakeLists.txt
file of your application:find_package(Zephyr HINTS $ENV{ZEPHYR_BASE})
The nRF Connect SDK allows you to create custom build type files instead of using a single
prj.conf
file.The nRF Connect SDK build system extends Zephyr’s with support for multi-image builds. You can find out more about these in the Multi-image builds section.
The nRF Connect SDK adds a partition manager, responsible for partitioning the available flash memory.
The nRF Connect SDK build system generates zip files containing binary images and a manifest for use with nRF Cloud FOTA.
Building FOTA images
The nRF Connect SDK build system places output images in the <build folder>/zephyr
folder.
If CONFIG_BOOTLOADER_MCUBOOT
is set, the build system creates the dfu_application.zip
file containing files app_update.bin
and manifest.json
.
If you have also set the options CONFIG_IMG_MANAGER
and CONFIG_MCUBOOT_IMG_MANAGER
, the application will be able to process FOTA updates.
If you have set the options CONFIG_SECURE_BOOT
and CONFIG_BUILD_S1_VARIANT
, a similar file dfu_mcuboot.zip
will also be created.
You can use this file to perform FOTA updates of MCUboot itself.
The app_update.bin
file is a signed version of your application.
The signature matches to what MCUboot expects and allows this file to be used as an update.
The build system creates a manifest.json
file using information in the zephyr.meta
output file.
This includes the Zephyr and nRF Connect SDK git hashes for the commits used to build the application.
If your working tree contains uncommitted changes, the build system adds the suffix -dirty
to the relevant version field.
Output build files
The building process produces each time an image file.
The image file can refer to an executable, a program, or an ELF file. As one of the last build steps, the linker processes all object files by locating code, data, and symbols in sections in the final ELF file. The linker replaces all symbol references to code and data with addresses. A symbol table is created which maps addresses to symbol names, which is used by debuggers. When an ELF file is converted into another format, such as HEX or binary, the symbol table is lost.
Depending on the application and the SoC, you can use one or several images.
The following table lists build files that can be generated as output when building firmware for supported build targets. The table includes files for single-core and multi-core programming scenarios for both Visual Studio Code and command line building methods. Which files you are going to use depends on the application configuration and not directly on the type of SoC you are using. The following scenarios are possible:
Single-image - Only one firmware image file is generated for a single core.
Multi-image - Two or more firmware image files are generated for a single core. You can read more about this scenario in Multi-image builds.
Multi-core - Two or more firmware image files are generated for two or more cores.
File |
Description |
Programming scenario |
---|---|---|
|
Default full image.
In a multi-image build, several |
|
|
The result of merging all |
|
|
The result of merging all |
|
|
Secure firmware image created by the TF-M build system in the background of the Zephyr build.
It is used together with the |
Programming SPE-only and multi-core build targets. |
|
Application core update file used to create |
DFU process for single-image build targets and the application core of the multi-core build targets. |
|
HEX file variant of the |
Programming single-image build targets and the application core of the multi-core build targets. |
|
Network core update file used to create |
DFU process for the network core of multi-core build targets. |
|
Zip file containing both the MCUboot-compatible update image for one or more cores and a manifest describing its contents. |
DFU process for both single-core and multi-core applications. |
|
Matter-specific OTA image that contains a Matter-compliant header and a DFU multi-image package that bundles user-selected firmware images. |
DFU over Matter for both single-core and multi-core applications. |
|
Zigbee-specific OTA image that contains the Zigbee application
with the Zigbee OTA header used for providing information about the image to the OTA server.
The <file_name> includes manufacturer’s code, image type, file version, and comment
(customizable by user, sample name by default).
For example: |
DFU over Zigbee for both single-core and multi-core applications in the nRF Connect SDK v2.0.0 and later. |
MCUboot output build files
File |
Description |
---|---|
|
Contains both the MCUboot-compatible update image for one or more cores and a manifest describing its contents ( |
|
Contains two versions of MCUBoot linked against different address spaces corresponding to slot0 (s0) and slot1 (s1) and a manifest JSON file describing their MCUBoot version number ( |
|
Signed variant of the firmware in binary format (as opposed to intelhex). It can be uploaded to a server as a FOTA image. |
|
MCUboot update for s0. |
|
MCUboot update for s1. |
|
Unsigned variant of the firmware in binary format. |
|
Signed variant of the firmware in intelhex format. This HEX file is linked to the same address as the application. Programming this file to the device will overwrite the existing application. It will not trigger a DFU procedure. |
|
Same as |
|
Same as |
|
Moved to MCUboot secondary slot address space. |
|
Directly overwrites s0. |
Other output build files
The following table lists secondary build files that can be generated when building firmware, but are only used to create the final output build files listed in the table above.
File |
Description |
---|---|
|
An ELF file for the image that is being built. Can be used for debugging purposes. |
|
A file with the Zephyr and nRF Connect SDK git hashes for the commits used to build the application. |
|
An ELF file for the TF-M image that is being built. Can be used for debugging purposes. |
|
Output artifact that uses information from the |
|
Multi-image package that contains a CBOR manifest and a set of user-selected update images, such as firmware images for different cores. Used for DFU purposes by Matter and Zigbee protocols. |