Building an application

After creating an application, you must set up a build configuration. A build configuration 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 panel, 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.
   Kconfig fragments	Select Kconfig fragments
   Extra CMake arguments	Enter additional CMake build arguments.
   Build directory name	Enter the 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 overlay file should be stored in this path samples/bluetooth/peripheral_lbs/nrf52dk_nrf52832.overlay.

   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. When you have finished configuring your build, click Build Configuration. The application starts building in the terminal view and the extension populates with several tool panels. Your configuration is complete when the build files appear in the build details panel.

   

Editing a build configuration

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

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

2. Click on the menu icon that is to the right.

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 steps 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 panel. 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 in the Applications panel, then hover to the right and click on Build All Configurations for Application.

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, follow these instructions during the build configuration setup.

1. Click Create a new board from the Welcome panel.
2. Enter your custom board information.
3. After the board is created, select your custom board 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 icon 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.

To unlink a device, click the button again.

Generating memory reports

To generate a memory report for your application:

1. Click Generate memory report in the Actions panel. A progress notification bar appears in the bottom right corner of the editor, which indicates that the report generation started.

2. When this has finished, two memory reports automatically open in the editor, 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.