Building an application

After creating an application, you must set up a build configuration to build an application. A build configuration is composed of different configuration options. It is essentially a CMake build system, which compiles and links the application components into a single image.

Setting up a build configuration

1. From the Applications View, click on the Add Build Configuration icon next to your application. This opens up the Add Build Configuration screen.

   

2. Fill in the configuration options according to your project needs. If you are using a custom board, follow the instructions in Adding a custom board.

   Configuration option	Description
   Board	Select the board that you want to work with.
   Configuration	Enter the name of the application configuration file. prj.conf is the default file.
   Kconfig fragments	Select Kconfig fragments. These depend on the features and configuration of each sample.
   Extra CMake arguments	Enter additional CMake build arguments. Append them with -- and put -D before each of them.
   Build directory name	Enter the custom name for the build directory.
   Build after generating configuration	The application is built after the configuration file is generated.
   Enable debug options	Debugging features are enabled after the application is built.

   Note

   The nRF Connect SDK has a preference for where to build overlay files. Read more about this in the nRF Connect SDK device tree overlay documentation. VS Code implements this rule set to determine which files should end up in the build, but ultimately it is the build system that decides. The most commonly used location is <application-root>/<board-id>.overlay.

   For example, for a build of the peripheral_lbs sample for nrf52dk_nrf52832, the nrf52dk_nrf52832.overlay file will be stored at samples/bluetooth/peripheral_lbs/.

   You can set custom overlay files by passing the argument -DDTC_OVERLAY_FILE=path/to/an/overlay_file.overlay in the Extra CMake arguments field when generating a build.

3. Click Build Configuration. The application starts building in the Terminal Panel View and the Sidebar populates with several Views. Your configuration is complete when the build files appear in the build Details View, which is named after your application.

   

Editing a build configuration

You can make changes to the configurations for any application you have already built.

1. In the Applications View, click on the build folder that contains the files you want to edit.

2. Click on the menu icon that is to the right, or right-click on the build folder.

3. Click on Edit Build Configuration.

4. After you have edited the configuration, click on Build Configuration to save your changes and rebuild the application with the new configuration.

Multiple build configurations

An application can have several build configurations that represent different CMake build systems. At any given time, only one build configuration (and thus application) is active.

You can create multiple build configurations for an application using the same setup steps as above. The additional build configuration appears under the selected application. The active build configuration is indicated by the blue icon.

If a build configuration has child images that target different cores, then those images will be grouped according to the separate cores.

To build multiple configurations at once for all applications in the current workspace, use the nRF Connect: Build All Configurations command or click the icon located in the top right corner of the Applications View. This will sequentially build all configurations for all existing applications in the current workspace.

To build multiple configurations only within a certain application, click on that application name within the Applications View, then hover to the right and click on Build All Configurations for Application.

Saving and sharing a build configuration

You can save a build configuration you have made for your application as a CMake Preset which stores the specific settings required for the build. Saving a preset stores this information in a CMakePresets.json file. This allows you to be able to easily share build configurations when working with others.

To save a build configuration, hover your mouse over the build folder and click on the menu icon More Actions > Save Configuration As Preset. This actions saves the current build configuration to the CMakePresets.json file, which appears after completing the action. Alternatively, you can run nRF Connect: Save Configuration as Preset through the Command Palette, which also saves the build configuration to the CMakePresets.json file.

The CMakePresets.json file can be applied to an application build in two different ways:

• Hover your mouse over the application, and click on the icon Add Build Configuration.

  1. When you have a CMakePresets.json file in your project you will see a CMake Preset field in the form. The field has a drop down with the currently available CMake Presets. Select one of the options, and the appropriate fields in the form will be filled with the values from the preset.
  2. Click on Build Configuration.

  

• Run the following command in the Terminal Panel View:

  west build -d ${targetDir} -- --preset ${presetName}
  

Specifying a board revision

If you select a board that has revisions, then a Board Revision input will appear. If you specify a revision in that field, then it will be passed to the west build command using the <board>@<revision> syntax.

Adding a custom board

If you have a custom board, complete the following steps before the build configuration setup to add it:

1. Click Create a new board from the Welcome View.
2. Enter your custom board information.
3. Click Create board.

After the board is created, you can select it from the Add Build Configuration screen.

Finding custom boards

The extension provides the BOARD_ROOT flag to CMake to indicate where to find custom boards. By default the extension considers all current workspace folders as board roots along with any entries in the nrf-connect.boardRoots setting. When you create a custom board with the Create a new board screen, the appropriate folder is added to your nrf-connect.boardRoots setting.

The same workspace folders and nrf-connnect.boardRoots entries are used to find custom boards to list in the Custom boards view in the Generate Configuration screen.

Linking a board to a build configuration

To link a connected board to a build configuration, click on the button next to your selected build configuration. Performing actions such as Flash on a build configuration with a linked device will always perform the action on that linked device.

Once the device is linked, the icon of the button changes to indicate the link. To unlink a device, click the button again.

Flashing an application

The nRF Terminal extension is an integrated serial port and RTT terminal.

From the Connected Devices View, use one of the following options:

• Click the button indicated in yellow to connect to a device over serial port.
• Click the button indicated in blue to connect over RTT.

After your board is connected, click on the Flash option from the Actions View. If you have multiple boards connected, you will be prompted to pick a device to flash at the top of the screen. Once the flashing starts, a small notification banner appears in the bottom right corner of VS Code to display the progress and confirm when the flashing is complete.

After changing parameters in your application, click on Build from the Actions View. If you have added or removed configuration files, then click the Pristine Build icon to the right of Build. Click on Flash to flash to the board again.

Tip

Create names or aliases for connected devices so that you do not have to remember their serial numbers. For more information, see the Creating device aliases section on the page about navigating the UI.

Flashing multiple build configurations

To flash multiple build configurations in parallel, use the nRF Connect: Flash All Linked Devices command or click the icon located in the Applications View Actions. This will flash all linked build configurations. This feature is not available if a board is linked to more than one build configuration.

Generating memory reports

To generate a memory report for your application:

1. Click Generate memory report in the Actions View. A progress notification bar appears in the bottom right corner of the screen.

2. When the report generation has finished, two memory reports automatically open in the editor within the same Webview, one for RAM and one for ROM.

   If you have several build configurations, a memory report will only be generated for the currently-selected build configuration.

   If you have an invalid build configuration, a failure warning will display when you try to generate the report.