Building and configuring an application for the Icarus

nRF Connect SDK v3.2.x

Building an application for the Icarus can be done in multiple ways. This guide explains how to build one of the Icarus sample applications using VS Code and West. West is the meta-tool of the Zephyr RTOS and is used, in combination with the Ninja build tool, by VS Code when building an application for the nRF9160.

Building an application using VS Code nRF Connect SDK extension

Building an application through VS Code is a straightforward and easy process. The nRF Connect SDK expansion pack for VS Code includes tools for configuration, building, debugging and flashing code. These steps show how to build a sample application for the Icarus in VS Code.

Building the application:

1. Choose and download an Icarus sample application from the samples section.
2. Open VS Code and click on the nRF connect icon in the left sidebar.
3. Click on Add an existing application and navigate to the desired sample directory.
4. Select the sample directory and click on Select folder.
5. Your sample should now be visible under the applications tab on the left. Click to add a new build configuration (You can have multiple build configuration for the same application. Useful if you are building the same application for multiple different boards).
6. Select the actinius_icarus/ns board. This will configure the build to be a non-secure application for the Icarus.
7. Click on Build Configuration. The application will now be built. You can open up a terminal and view the building process using CTRL+`.

Building an application using West

West is a "swiss-army knife" command-line tool used to manage application repositories that use the Zephyr RTOS. It can be used for building, flashing and debugging among many other functionalities. Check out the West documentation for more information.

Opening a terminal with the toolchain environment:

You have several options to open a terminal with west and the toolchain ready to use:

• VS Code: Open the nRF Connect extension, click on an SDK version under "SDK environments", and select Open terminal.
• nrfutil: Run nrfutil sdk-manager toolchain launch --ncs-version v3.2.1 --shell (replace the version with your installed SDK version; use --terminal on Windows).
• Manual installation: Source the environment script as described in the toolchain installation guide.

Building the application:

1. Choose and download an Icarus sample application from the samples section.

2. Open a terminal with the toolchain environment configured (see above).

3. Navigate to your sample application directory and build the sample:

$ cd <path-to-sample-dir>
$ west build -b actinius_icarus/ns

Sysbuild

Starting with nRF Connect SDK v3.0, sysbuild is the default build system. When building from the command line with older SDK versions, add --sysbuild to the west build command. The VS Code nRF Connect extension handles this automatically.

West will now build the sample application and create a build directory. To rebuild the application at any time, repeat step 3. Rebuilding does not require the -b option.

4. West can also run a clean (pristine) build using the following commands:

$ west build -b actinius_icarus/ns -p

Configuration and build system

The configuration and build system of the nRF connect SDK is largely based on the Zephyr project. Applications for the nRF9160 are built using the following tools:

• Kconfig: This system is used for kernel configuration of the Zephyr RTOS. It is the same configuration system that is used for configuring the Linux kernel. Configuration options are used to turn certain kernel features on/off, modify settings, or enable/disable certain subsystems. These configuration options are defined in Kconfig files and can be referenced to in the source code of an application. They usually have the form of CONFIG_<OPTION>. More information on Kconfig in the Zephyr documentation on Kconfig.
• Device-tree: This is yet another system that is coming from the Linux world. The device-tree is used to describe hardware for the Zephyr RTOS. The Icarus board has its own device-tree which can be found here. More information on the device-tree can be found in Zephyr's device-tree guide.
• CMake: This system is used for generating build files and scripts. In the nRF Connect SDK, it is used in combination with the Ninja build tool to build the user application and Zephyr kernel. More information can be found in the Zephyr documentation on CMake.
• Ninja: Ninja is the build tool used by the nRF Connect SDK. It is similar to make.
• GCC: The GCC compiler is used to compile all source code. The linker then takes all blobs generated by GCC and links them together to create the final binaries for the nRF9160.

A diagram of how all the components of the build system are connected can be seen in the image below (source: nRF Connect SDK docs). The base of the configuration and build system rests on Kconfig and the device-tree.

nRF Connect SDK configuration and build system

User application project structure

The user application, Zephyr kernel, subsystems, and libraries are configured through a set of files available in the project directory. A project directory has the following contents:

<app-project-dir>
├── CMakeLists.txt
├── prj.conf
├── sysbuild.conf
├── build
|   ├── <app_name>/
|   |   ├── zephyr/
|   |   └── tfm/
|   ├── mcuboot/
|   ├── merged.hex
|   ├── dfu_application.zip
|   └── ...
└── src
    ├── main.c
    └── ...

file / directory	description
build/	Contains the build files that are created during the building process by CMake. With sysbuild, merged.hex and dfu_application.zip are at the build root, while per-image outputs (application, MCUBoot, TF-M) are in their own subdirectories.
src/	Contains the source files of the user application. This directory can contain libraries and their Kconfig files for enabling/disabling certain modules.
CMakeLists.txt	This file configures the building process and tells the build system where to find the source files of the application and what to build.
prj.conf	This is a Kconfig configuration file. It is used to configure the Zephyr kernel, libraries, modules, and subsystems user configuration options. The configuration options can be added manually or can be modified through menuconfig.
sysbuild.conf	This is the sysbuild Kconfig file for sysbuild-level options (prefixed with SB_CONFIG_). Use this to enable features like MCUBoot (SB_CONFIG_BOOTLOADER_MCUBOOT=y). Per-image overrides can be placed in sysbuild/<image>.conf.

Configuration using menuconfig or a GUI

As mentioned in the table above, configuration of the kernel and other parts of the application can be done through menuconfig (provided by West). Menuconfig is a menu-like user interface in the terminal that displays all the configuration options and allows you to change them. West also provides a way to change the configuration options through a GUI. These commands can be used to change an application configuration:

# For application configuration through menuconfig
$ west build --target menuconfig

# For sysbuild configuration through menuconfig
$ west build --target sysbuild_menuconfig

# For configuration through a GUI
$ west build --target guiconfig

The changes that are made in the provided menus will be apparent in the prj.conf file (or sysbuild.conf for sysbuild options). Using the menus is useful to explore and find the different configuration options that are needed for your project. Not all available options are present in the menus. For these options you still need to manually edit the configuration files.

The nRF Connect for VS Code extension also provides a graphical Kconfig editor that can be used as an alternative to menuconfig and guiconfig.