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:
- From the Applications View, click on the Add Build Configuration icon next to your application.
This opens up the Add Build Configuration screen.
-
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 thenrf52dk_nrf52832
build target, thenrf52dk_nrf52832.overlay
file will be stored atsamples/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. -
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.
- 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:
- In the Applications View, click on the build folder that contains the files you want to edit.
- Click on the menu icon that is to the right, or right-click on the build folder.
- Click on Edit Build Configuration.
- 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:
- Hover your mouse over the build folder.
- 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:
- Hover your mouse over the application name. A couple of icons appear.
- 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. - Select one of the CMake Preset options. The appropriate fields in the form will be filled with the values from the preset.
- 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}