Adding files and configuring CMake

As described in more detail in Build and configuration system, the Zephyr and nRF Connect SDK build systems are based on CMake. For this reason, every application in Zephyr and the nRF Connect SDK must have a CMakeLists.txt file. This file is the entry point of the build system as it specifies the application source files for the compiler to include in the configuration phase.

Maintaining CMakeLists.txt

The recommended method to maintain and update the CMakeLists.txt file is to use nRF Connect for VS Code. The extension provides support for the source control with west and CMake build system, including build configuration management and source and config files overview.

Adding source files to CMakeLists.txt

You can add source files to the app CMake target with the target_sources() function provided by CMake.

Pay attention to the following configuration options:

  • If your application is complex, you can split it into subdirectories. These subdirectories can provide their own CMakeLists.txt files. (The main CMakeLists.txt file needs to include those.)

  • The build system searches for header files in include directories. Add additional include directories for your application with the target_include_directories() function provided by CMake. For example, if you want to include an inc directory, the code would look like the following:

    target_include_directories(app PRIVATE inc)

See Application CMakeLists.txt in the Zephyr documentation for more information about how to edit CMakeLists.txt.

Note

You can also read the CMake Tutorial in the CMake documentation for a better understanding of how CMakeLists.txt are used in a CMake project. This tutorial however differs from Zephyr and nRF Connect SDK project configurations, so use it only as reference.

Providing CMake options

You can provide additional options for building your application to the CMake process, which can be useful, for example, to switch between different build scenarios. These options are specified when CMake is run, thus not during the actual build, but when configuring the build.

The nRF Connect SDK uses the same CMake build variables as Zephyr and they are compatible with both CMake and west. The parameters and options passed in the command line always take precedence over west config settings.

For the complete list of build variables in Zephyr and more information about them, see Important Build System Variables in the Zephyr documentation.

Note

The Partition Manager is a component in the nRF Connect SDK and is responsible for handling the memory partitioning at build time.

This functionality is in the process of being deprecated and replaced by Zephyr’s default devicetree-based memory partitioning. It is recommended that all new designs using Nordic devices, excluding the nRF91 Series devices, are to be built with DTS instead of Partition Manager. Partition Manager will be removed from the nRF Connect SDK by the end of 2026 from the main branch.

For more information on how to configure partitions using DTS and how to migrate your existing configuration to DTS, see the following pages:

The following table lists the most common ones used in the nRF Connect SDK:

Common build system variables in the nRF Connect SDK

Variable

Purpose

CMake argument to use

Name of the Kconfig option
Set the given Kconfig option to a specific value for a single build.
The Kconfig option name can be subject to variable namespacing and sysbuild Kconfig namespacing.

-D<name_of_Kconfig_option>=<value>

CONF_FILE
Select the base Kconfig configuration file to be used for your application and override the autoselection process.
This variable has also been used to select one of the available build types, if the application or sample supports any.
Using this variable for build type selection is deprecated and is being gradually replaced by FILE_SUFFIX, but still required for some applications.
-DCONF_FILE=<file_name>.conf
-DCONF_FILE=prj_<build_type_name>.conf

SB_CONF_FILE

Select the base sysbuild Kconfig configuration file to be used for your application and override the autoselection process.

-DSB_CONF_FILE=<file_name>.conf

EXTRA_CONF_FILE

Provide additional Kconfig fragment files to be “mixed in” with the base configuration file.

-DEXTRA_CONF_FILE=<file_name>.conf

DTC_OVERLAY_FILE

Select the base devicetree overlay files to be used for your application and override the autoselection process.

-DDTC_OVERLAY_FILE=<file_name>.overlay

EXTRA_DTC_OVERLAY_FILE

Provide additional, custom devicetree overlay files to be “mixed in” with the base devicetree overlay file.

-DEXTRA_DTC_OVERLAY_FILE=<file_name>.overlay

SHIELD

Select one of the supported shields for building the firmware.

-DSHIELD=<shield> (-D<image_name>_SHIELD for images)

FILE_SUFFIX
Select one of the available suffixed configurations, if the application or sample supports any.
See Custom configurations for more information about their usage and limitations in the nRF Connect SDK.
This variable is gradually replacing CONF_FILE for selecting build types.

-DFILE_SUFFIX=<configuration_suffix> (-D<image_name>_FILE_SUFFIX for images)

-S (west) or SNIPPET (CMake)

Select one of the Snippets to add to the application firmware during the build.
-S <name_of_snippet> (applies the snippet to all images)
-DSNIPPET=<name_of_snippet> (-D<image_name>_SNIPPET=<name_of_snippet> for images)

PM_STATIC_YML_FILE
Select a static configuration file for the Partition Manager script.
For applications that do not use multiple images, the static configuration can be selected with FILE_SUFFIX (see above).

-DPM_STATIC_YML_FILE=pm_static_<suffix>.yml

You can use these parameters in both nRF Connect for VS Code and the command line.

The build variables are applied one after another, based on the order you provide them. This is how you can specify them:

See How to build an application in the nRF Connect for VS Code documentation. You can specify the additional configuration variables when setting up a build configuration:

  • FILE_SUFFIX (and CONF_FILE) - Select the configuration in the Base configuration files menu.

  • EXTRA_CONF_FILE - Add the Kconfig fragment file in the Extra Kconfig fragments menu.

  • DTC_OVERLAY_FILE - Select the configuration in the Base devicetree overlays menu.

  • EXTRA_DTC_OVERLAY_FILE - Add the devicetree overlays in the Extra devicetree overlays menu.

  • SNIPPET - Select the snippet from the list in the Snippets menu.

  • Other variables - Provide CMake arguments in the Extra CMake arguments field, preceded by --.

For example, to build the Cellular: Location sample for the nRF9161 DK with the nRF7002 EK Wi-Fi® support, select nrf9161dk/nrf9161/ns in the Board menu, overlay-nrf7002ek-wifi-scan-only.conf in the Extra Kconfig fragments menu, and provide -- -DSHIELD=nrf7002ek in the Extra CMake arguments field.

See Permanent Kconfig changes and Zephyr’s One-Time CMake Arguments for more information.

Examples of commands

Providing a CMake variable for build types

To select the build type in nRF Connect for VS Code:

  1. When building an application as described in the nRF Connect for VS Code documentation, follow the steps for setting up the build configuration.

  2. In the Add Build Configuration screen, select the desired .conf file from the Configuration drop-down menu.

  3. Fill in other configuration options, if applicable, and click Build Configuration.

If the selected board does not support the selected build type, the build is interrupted.

Providing CMake options for specific images

You can prefix the build variable names with the image name if you want the variable to be applied only to a specific image: -D<prefix>_<build_variable>=<file_name>. For example, -DEXTRA_CONF_FILE=external_crypto.conf will be applied to the default image for which you are building (most often, the application image), while -Dmcuboot_EXTRA_CONF_FILE=external_crypto.conf will be applied to the MCUboot image.

This feature is not available for setting Kconfig options.