Build and configuration system

The nRF Connect SDK build and configuration system is based on the one from Zephyr, with some additions.

Overview of build and configuration system

The build and configuration system in Zephyr and the nRF Connect SDK uses the following building blocks as a foundation:

Configuration system overview

Source	File types	Usage	Available dedicated editing tools	Additional information
CMake	CMakeLists.txt, .cmake	Build system generator.	n/a	CMake is used to build your application together with the Zephyr kernel.
Devicetree	.dts, .dtsi, .overlay	Hardware description language.	Devicetree Visual Editor	Devicetree Visual Editor is part of the nRF Connect for VS Code extension. You still need to be familiar with the devicetree language to use it.
Kconfig	Kconfig, prj.conf, .config	Software configuration system also used in the Linux kernel.	Kconfig GUI, menuconfig and guiconfig	Kconfig GUI is part of the nRF Connect for VS Code extension. The Kconfig Reference provides the documentation for each configuration option.
Partition Manager	pm.yml, pm_static.yml	Memory layout configuration system.	Partition Manager script	Partition Manager is an nRF Connect SDK configuration system that is not available in Zephyr.

Each of these systems comes with a specialized syntax and purpose. See the following sections for more information. To read more about Zephyr’s configuration system and its role in the application development, see Build and Configuration Systems and Application Development in the Zephyr documentation.

When you create an application, the configuration files for each of these systems are created in the application directory: CMakeLists.txt for CMake, app.overlay for devicetree, prj.conf for Kconfig, and partitions.yml for Partition Manager (if enabled). You can then edit them according to your needs (see Building an application).

When you start building, a CMake build is executed in two stages: configuration phase and building phase.

nRF Connect SDK tools and configuration methods

Configuration phase

During this phase, CMake executes build scripts from CMakeLists.txt and gathers configuration from different sources, for example Custom configurations, to generate the final build scripts and create a model of the build for the specified board target. The result of this process is a build configuration, a set of files that will drive the build process.

For more information about this phase, see the respective sections on Zephyr’s Build System (CMake) page, which describes in-depth the usage of CMake for Zephyr-based applications.

Role of CMakeLists.txt

In Zephyr and the nRF Connect SDK, the application is a CMake project. As such, the application controls the configuration and build process of itself, Zephyr, and sourced libraries. The application’s CMakeLists.txt file is the main CMake project file and the source of the build process configuration.

Zephyr provides a CMake package that must be loaded by the application into its CMakeLists.txt file. When loaded, the application can reference items provided by both Zephyr and the nRF Connect SDK.

Loading Zephyr’s CMake package creates the app CMake target. You can add application source files to this target from the application CMakeLists.txt file. See Adding source files to CMakeLists.txt for detailed information.

Hardware-related configuration

*.dts (devicetree source) and *.dtsi (devicetree source include) files are collected from the target’s architecture, SoC, board, and application directories.

*.dtsi files are included by *.dts files via the C preprocessor (often abbreviated cpp, which should not be confused with C++). The C preprocessor is also used to merge in any devicetree *.overlay files, and to expand macros in *.dts, *.dtsi, and *.overlay files. The preprocessor output is placed in build/zephyr/zephyr.dts.pre.

The preprocessed devicetree sources are parsed by the zephyr/scripts/dts/gen_defines.py script to generate a devicetree_unfixed.h header file with preprocessor macros.

The zephyr.dts file contains the entire hardware-related configuration of the system in the devicetree format. The header file contains the same kind of information, but with defines usable by source code.

For more information, see Configuring devicetree and Zephyr’s Devicetree Guide. In particular, Set devicetree overlays explains how the base devicetree files are selected.

In the nRF Connect SDK, you can use the nRF Connect for VS Code extension to create the devicetree files and work with them using the dedicated Devicetree Visual Editor. You can also select the devicetree files when Providing CMake options.

Software-related configuration

Kconfig files define available configuration options for the target architecture, SoC, board, and application, as well as dependencies between options.

Kconfig configurations are stored in configuration files. The initial configuration is generated by merging configuration fragments from the board and application (e.g. prj.conf).

The output from Kconfig is an autoconf.h header with preprocessor assignments, and a .config file that acts both as a saved configuration and as configuration output (used by CMake). The definitions in autoconf.h are automatically exposed at compile time, so there is no need to include this header.

Information from devicetree is available to Kconfig, through the functions defined in zephyr/scripts/kconfig/kconfigfunctions.py.

The .config file in the <build_dir>/zephyr/ directory describes most of the software configuration of the constructed binary. Some subsystems can use their own configuration files.

For more information, see Zephyr’s Kconfig Configuration. In particular, The Initial Configuration explains how the base configuration files are selected.

In the nRF Connect SDK, just as in Zephyr, you can configure Kconfig temporarily or permanently. You can also select the Kconfig options and files when Providing CMake options.

The Kconfig Reference provides the documentation for each configuration option in the nRF Connect SDK.

Memory layout configuration

The memory layout configuration is provided by the Partition Manager script, specific to the nRF Connect SDK.

The script must be enabled to provide the memory layout configuration. It is impacted by various elements, such as Kconfig configuration options or the presence of child images. Partition Manager ensures that all required partitions are in the correct place and have the correct size.

If enabled, the memory layout can be controlled in the following ways:

• Dynamically (default) - In this scenario, the layout is impacted by various elements, such as Kconfig configuration options or the presence of child images. Partition Manager ensures that all required partitions are in the correct place and have the correct size.

• Statically - In this scenario, you need to provide the static configuration. See Static and dynamic configuration for information about how to do this.

After CMake has run, a partitions.yml file with the memory layout will have been created in the build directory. This process also creates a set of header files that provides defines, which can be used to refer to memory layout elements.

Child images

Important

This feature is deprecated and is being replaced by Zephyr’s Sysbuild (System build). You can continue to use it until the transition is complete in the nRF Connect SDK and the feature is removed in one of the upcoming nRF Connect SDK releases. For more information, see Sysbuild (System build), Sysbuild images, Using Zephyr samples with sysbuild, and Sysbuild forced options.

The nRF Connect SDK build system allows the application project to become a root for the sub-applications known in the nRF Connect SDK as child images. Examples of child images are bootloader images, network core images, or security-related images. Each child image is a separate application.

For more information, see Multi-image builds using child and parent images.

Custom configurations

Zephyr provides the File Suffixes feature for applications that require a single code base with multiple configurations for different product or build variants (or both). When you select a given file suffix for the configuration phase, the build system will use a specific set of files to create a specific build configuration for the application. If it does not find files that match the provided suffix, the build system will fall back to the default files without suffix.

The file suffix can be any string, but many applications and samples in the nRF Connect SDK use release. This suffix can be included in the prj.conf file name (for example, prj_release.conf), and also in file names for board configurations, child image Kconfig configurations, and others. In this way, these files are made dependent on the given configuration and are only used when that build configuration is generated. For example, if an application uses a custom nrf5340dk_nrf5340_cpuapp_release.overlay overlay file, this file will be used together with the application’s prj_release.conf when you set FILE_SUFFIX to release (-DFILE_SUFFIX=release).

Many applications and samples in the nRF Connect SDK define even more detailed build configurations. For example, the Zigbee light switch sample features the fota configuration. See the Configuration section of the given application or sample’s documentation for information on if it includes any custom configurations.

Important

The file suffixes feature is replacing the Custom build types that used the CONF_FILE variable. File suffixes are backward compatible with this variable. Some applications might still require using the CONF_FILE variable during the deprecation period of the build types.

For information about how to provide file suffixes when building an application, see Providing CMake options.

Snippets

Snippets are a Zephyr mechanism for defining portable build system overrides that could be applied to any application. Read Zephyr’s Snippets documentation for more information.

Important

When using Sysbuild, the snippet is applied to all images, unless the image is specified explicitly (-D<image_name>_SNIPPET="<your_snippet>").

You can set snippets for use with your application when you set up your build configuration by providing them as CMake options.

Usage of snippets is optional.

Building phase

During this phase, the final build scripts are executed. The build phase begins when the user invokes make or ninja. The compiler (for example, GCC compiler) then creates object files used to create the final executables. You can customize this stage by Providing CMake options and using Advanced compiler settings.

The result of this process is a complete application in a format suitable for flashing on the desired board target. See output build files for details.

The build phase can be broken down, conceptually, into four stages: the pre-build, first-pass binary, final binary, and post-processing. To read about each of these stages, see Build System (CMake) in the Zephyr documentation.

Sysbuild

The nRF Connect SDK supports Zephyr’s System Build (sysbuild).

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.

To distinguish CMake variables and Kconfig options specific to the underlying build systems, sysbuild uses namespacing. For example, sysbuild-specific Kconfig options are preceded by SB_ before CONFIG and application-specific CMake options are preceded by the application name.

Sysbuild is integrated with west. The sysbuild build configuration is generated using the sysbuild’s CMakeLists.txt file (which provides information about each underlying build system and CMake variables) and the sysbuild’s Kconfig options (which are gathered in the sysbuild.conf file).

Note

In the nRF Connect SDK, building with sysbuild is enabled by default.

For more information about sysbuild, see Configuring sysbuild and the Sysbuild documentation in Zephyr.

Additions specific to the nRF Connect SDK

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 packages.

You must be aware of these additions when you start writing your own applications based on this SDK.

Experimental option enabled by default

Unlike in Zephyr, the Kconfig option CONFIG_WARN_EXPERIMENTAL is enabled by default in the nRF Connect SDK. 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.

To disable these warnings, disable the CONFIG_WARN_EXPERIMENTAL Kconfig option.

Sysbuild enabled by default

Sysbuild in the nRF Connect SDK works differently than in Zephyr.

The nRF Connect SDK modifies the default behavior of west build, so that the standard building procedure will use sysbuild by default for repository applications in the SDK repositories. For this reason, unlike in Zephyr, --sysbuild does not have to be explicitly mentioned in the command prompt when building a repository application. This setting only applies to repositories delivered with the nRF Connect SDK, to maintain compatibility with child/parent images.

This setting does not apply to out-of-tree applications, such as workspace or freestanding applications. In such cases, once you ported your application to sysbuild, it is up to you to either use the --sysbuild parameter on the command line every time you build or to configure west to always use it.

Moreover, this nRF Connect SDK setting does not apply to the following areas:

• Twister will not use sysbuild unless tests are updated.

• CMake will not configure projects using sysbuild unless the invocation command is updated.

Custom build types

Important

This feature is deprecated and is being replaced by suffix-based configurations. You can continue to use it until the transition is complete in the nRF Connect SDK and the feature is removed in one of the upcoming nRF Connect SDK releases. It is still required for some applications that use build types with multiple images. Check the application and sample documentation pages for which variable to use.

A build type is a feature that defines the way in which the configuration files are to be handled. For example, selecting a build type lets you generate different build configurations for release and debug versions of the application.

In the nRF Connect SDK, the build type is controlled using the configuration files, whose names can be suffixed to define specific build types. When you select a build type for the configuration phase, the compiler will use a specific set of files to create a specific build configuration for the application.

The prj.conf file is the application-specific default, but many applications and samples include source files for generating the build configuration differently, for example prj_release.conf or prj_debug.conf. Similarly, the build type can be included in file names for board configuration, Partition Manager’s static configuration, child image Kconfig configuration, and others. In this way, these files are made dependent on the build type and will only be used when the corresponding build type is invoked. For example, if an application uses pm_static_release.yml to define Partition Manager’s static configuration, this file will only be used when the application’s prj_release.conf file is used to select the release build type.

Many applications and samples in the nRF Connect SDK use build types to define more detailed build configurations. The most common build types are release and debug, which correspond to CMake defaults, but other names can be defined as well. For example, nRF Desktop features a wwcb build type, while Matter weather station features the factory_data build type. See the application’s Configuration section for information if it includes any build types.

The following software components can be made dependent on the build type:

• The Partition Manager’s static configuration. When the build type has been inferred, the file pm_static_<buildtype>.yml will have precedence over pm_static.yml.

• The child image Kconfig configuration. Certain child image configuration files located in the child_image/ directory can be defined per build type.

The devicetree configuration is not affected by the build type.

For more information about how to invoke build types, see Providing CMake options.

Multi-image builds

Important

This feature is deprecated and is being replaced by Zephyr’s Sysbuild (System build). You can continue to use it until the transition is complete in the nRF Connect SDK and the feature is removed in one of the upcoming nRF Connect SDK releases. For more information, see Sysbuild (System build), Sysbuild images, Using Zephyr samples with sysbuild, and Sysbuild forced options.

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 using child and parent images section.

The nRF Connect SDK allows you to build types instead of using a single prj.conf file.

Boilerplate CMake file

The nRF Connect SDK provides an additional boilerplate.cmake file that is automatically included when using the Zephyr CMake package in the CMakeLists.txt file of your application:

find_package(Zephyr HINTS $ENV{ZEPHYR_BASE})

This file checks if the selected board is supported and, when available, if the selected file suffix or build type is supported.

Partition Manager

The nRF Connect SDK adds the Partition Manager script, responsible for partitioning the available flash memory and creating the Memory layout configuration.

Binaries and images for nRF Cloud FOTA

The nRF Connect SDK build system generates output zip files containing binary images and a manifest for use with nRF Cloud FOTA. An example of such a file is dfu_mcuboot.zip.