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 Configuring and 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 build 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 to use devicetree and its overlays to customize an application’s devicetree.

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 Configuring and building an application and Zephyr’s Kconfig Configuration. 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 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

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.

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, but the following software components are not compatible with file suffixes:

• Child image Kconfig configuration. Use the CONF_FILE variable during the deprecation period of the build types.

• The Partition Manager’s static configuration does not yet support the FILE_SUFFIX variable. To ensure that the file pm_static_<suffix>.yml will have precedence over pm_static.yml when building for a selected FILE_SUFFIX, make sure to also provide the PM_STATIC_YML_FILE variable set to pm_static_<suffix>.yml. Alternatively, you can use the previously used CONF_FILE variable (which is now deprecated), until support for it is removed.

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

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 target board. 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.

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.

Custom build types

Important

The build types are deprecated and are being replaced by suffix-based configurations and Zephyr’s Sysbuild (System build). You can continue to use the build types feature until the transition is complete in the nRF Connect SDK. It is still required for applications that use build types with multiple images or Partition Manager’s static configuration (or both). 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

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

Note

The Partition Manager’s static configuration does not yet support the FILE_SUFFIX variable. To ensure that the file pm_static_<suffix>.yml will have precedence over pm_static.yml when building for a selected FILE_SUFFIX, make sure to also provide the PM_STATIC_YML_FILE variable set to pm_static_<suffix>.yml. Alternatively, you can use the previously used CONF_FILE variable (which is now deprecated), until support for it is removed.

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.