Building an application
For simplicity, this guide will refer to both samples and applications as “applications”.
After you have created an application, you need to build it in order to be able to program it. Just as for creating the application, you can build the application using either the nRF Connect for VS Code extension or the command line.
To build with the nRF Connect for VS Code extension, you first need to create a build configuration. For instructions, see How to build an application in the extension documentation.
By default, the extension runs both stages of the CMake build (configuration phase and building phase). If you want to only set up the build configuration without building it, make sure the Build after generating configuration is not selected.
To build with Sysbuild, keep the default setting selected or select the Use sysbuild radio button.
If you want to build with custom options or scripts, read about Binding custom tasks to actions in the extension documentation.
Note
Some samples in the nRF Connect SDK are currently not designed to work out-of-tree. You may need to manually configure your sample to work correctly in the nRF Connect for VS Code extension.
For more information about files generated as output of the build process, see Output build files (image files).
Complete the following steps to build on the command line:
Start the toolchain environment in a terminal window.
Go to the specific application directory.
For example, if you want to build the Cellular: AT Client sample, run the following command to navigate to its directory:
cd nrf/samples/cellular/at_clientBuild the application by using the following west command with the board_target specified:
west build -b board_target
See Board names for more information on the supported boards and board targets. The board targets supported for a given application are always listed in its requirements section.
When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the
--sysbuildparameter to every build command or configure west to always use it.The command can be expanded with Optional build parameters, such as custom CMake options or the
--no-sysbuildparameter that disables building with sysbuild. The parameters and options passed in the command line always take precedence overwest configsettings.
After running the
west buildcommand, the build files can be found in the main build directory or in the application-named sub-directories in the main build directory (or both, depending on your project structure). For more information about files generated as output of the build process, see Output build files (image files). For more information on the contents of the build directory, see Build Directory Contents in the Zephyr documentation.For more information on building using the command line, see Building in the Zephyr documentation.
Note
On Windows, because of the Windows path length limitations, the build can fail with errors related to permissions or missing files if some paths in the build are too long.
To avoid this issue, shorten the build folder name, for example to build, or shorten the path to the build folder in some other way.
Advanced building procedures
You can customize the basic building procedures in a variety of ways, depending on the configuration of your project.
Advanced compiler settings
The application has full control over the build process.
Using Zephyr’s configuration options is the standard way of controlling how the system is built.
These options can be found under Zephyr’s menuconfig Build and Link Features > Compiler Options.
For example, to turn off optimizations, select CONFIG_NO_OPTIMIZATIONS.
Compiler options not controlled by the Zephyr build system can be controlled through the CONFIG_COMPILER_OPT Kconfig option.
Common sample components for development
Code found in the samples/common are not intended to be used independently, but in addition to other compatible samples for development purposes.
For example, the file path samples/common/mcumgr_bt_ota_dfu contains the source for the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option.
This Kconfig option can be used with specific Nordic Semiconductor devices to enable MCUmgr to perform firmware over-the-air (FOTA) updates using Bluetooth® Low Energy.
To learn more about how to use the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option, see the respective device guides for nRF52 Series and the nRF5340 DK.
Optional build parameters
You can customize the basic west build command in a variety of ways.
The following table contains some of the commonly used parameters in the nRF Connect SDK.
For more options, see Zephyr’s Building: west build or run the west --help and west build --help commands.
The parameters and options passed in the command line always take precedence over west config settings.
Parameter |
Usage |
Example |
|---|---|---|
Provide additional options for building your application to the CMake process. |
See the dedicated section |
|
|
Explicitly build without Sysbuild. (In the nRF Connect SDK, building with sysbuild is enabled by default.) |
|
|
Enable a detailed Verbose Builds log, which includes the full commands used by the build system to generate the Output build files (image files). |
|
directory_name |
Build from a directory other than the current directory. |
|
|
Specify the build directory where the Output build files (image files) are to be placed.
If not specified, the build files are automatically generated in |
|
|
Build for a single domain in a multi-domain build. This parameter can also be used for programming and debugging multiple domains. |
|
|
Start menuconfig to configure your application’s Kconfig options. |
|
|
Reuse an existing build directory for building another application for another board or board target. |
|
|
Run unit tests with the west command from the unit test directory (with the |
|