How to work with build configurations

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

How to set up a build configuration

To set 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 (see the fields' tooltips.)
   If you are using a custom board, follow the instructions in How to add a new board.

   Note

   The nRF Connect SDK has a preference for where to build overlay files. Read more about this in the nRF Connect SDK devicetree 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 the nrf52dk_nrf52832 build target, 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. Optionally, select one of the following checkboxes:

   • Build after generating configuration - Select to build the application after the configuration file is generated.
   • Enable debug options - Select to enable additional nRF Debug features after the application is built.
4. Click Build Configuration.
   The application starts building and the Sidebar populates with several new Views. Your configuration is complete when the build files appear in the build Details View, which is named after your application (TEST-APP in the following image.)

Once the build is complete, you can use the Build button from the Actions View to rebuild the application.

How to specify the board revision

If you select a board that has revisions, then the Revision field appears on the Add Build Configuration screen. If you specify the board revision in this field, then its value will be passed to the west build command using the <board>@<revision> syntax.

How to edit build configurations

You can make changes to the configurations for any application you have already built. You can do this as follows:

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.

Tip

Customize the Build action by assigning different tasks to it. Read Build and flash task configuration for more information.

How to save 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 share build configurations when working with others.

To save a build configuration:

1. Hover your mouse over the build folder.
2. Click on the menu icon More Actions > Save Configuration As Preset.
   This action 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 from the Command Palette, which also saves the build configuration to the CMakePresets.json file.

How to create a build configuration from a preset

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

From the Applications View

Complete the following steps in the Applications View:

1. Hover your mouse over the application name.
   A couple of icons appear.
2. Click on the icon Add Build Configuration to open up the screen for adding a build configuration.
   When you have a CMakePresets.json file in your project, the form will feature a CMake Preset field. The field has a drop-down menu with the currently available CMake Presets.
3. Select one of the CMake Preset options.
   The appropriate fields in the form will be filled with the values from the preset.
4. Click on Build Configuration.

From the Panel View

Run the following command in an instance of the nRF Connect terminal profile, one of the three dedicated terminal profiles in the Panel View:

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