Skip to content

Build and flash task configuration

The extension lets you customize tasks assigned to the Build and Flash actions. You can do this using different methods, described in the following sections.

Bind Task to Action feature

You can bind custom tasks to most of the build and flash actions. When bound, these tasks will run instead of the standard commands. This is useful if you want to run a custom script that hooks into your own build system, or that performs pre- or postprocessing steps.

You can add custom tasks to the following actions:

  • Build Ctrl+Alt+B
  • Pristine Build Ctrl+Shift+Alt+B
  • Flash Ctrl+Alt+P
  • Erase and Flash to Board Ctrl+Alt+E

Bindings created using this interface are stored in the nrf-connect.taskBindings property in either the settings.json file or under the settings key in your workspace file, depending on the structure of your project. You can modify this property manually, which can be easier if you have many bindings or a complicated setup.

Binding tasks

To bind a task to an action:

  1. Hover your cursor over Build or Flash from the Actions View.
  2. Click on the More actions... button (with the three dot icon) that appears to the right.
  3. Click on Bind Task to Action.
  4. A quick-pick menu appears in the Editor. Click on the action you want to bind.
  5. Click on the builds you want to bind to the action.

Binding two custom tasks to an action

You can manually create task bindings in the settings file by referencing the tasks defined in the correct tasks.json file. You can read more about how this works and how to configure tasks in the correct file in the Manually adding and customizing tasks section of this page.

Once you have bound tasks to an action, view them by hovering your mouse over Build or Flash, whichever you have bound the task to, and they will appear in the help text.

Note

Task bindings only apply to the primary Build command. They do not apply to the action Build All.

Unbinding tasks

To unbind tasks from an action, right-click on Build or Flash and then click Remove Task Binding. If multiple tasks are bound, select which one you wish to remove.

Manually adding and customizing tasks

You can define bound tasks in several locations, depending on the structure of your project.

Single-folder project Multi-root workspace
Adding a new task tasks.json tasks key in *.code-workspace
Bind Task to Action settings.json settings key in *.code-workspace

For more information on where tasks should be defined and what format they should take, read the VS Code tasks documentation.

Configuration file locations

When working with a single-folder project, the settings.json file is automatically created in the .vscode directory, while the tasks.json file must be created manually.

If you are working with a multi-root workspace, you may be missing the *.code-workspace file if you have opened a workspace, but not saved it. Once you save the workspace, you will be able to open it from the Actions View by clicking More Actions... > Open Tasks File. You can then edit the file by adding the tasks key or editing the settings key.

Example of a single task

For example, let's assume you have a tasks.json file. If you have only one task that you would like to bind to an action, the file may look like follows:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "My custom flash",
            "command": "${workspaceFolder}/my-flash-script.sh",
            "args": ["--build", "--erase", "--nrf52"],
            "presentation": {
                "echo": true,
                "reveal": "never",
                "clear": true
            }
        }
    ]
}

You can bind the task to the action by adding the following lines to the nrf-connect.taskBindings configuration option:

{
    "nrf-connect.taskBindings": {
        "build": [{ "taskName": "My custom flash" }]
    }
}

This way, the My custom flash task will be executed whenever the Build action is run.

Tasks are matched by their label attribute. If a task is referenced in the configuration, but is not defined in the tasks.json file or contributed by an extension, a warning message appears until the binding is removed.

Example of a restricted single task

You can also restrict task bindings to a given build configuration or a set of build configurations. For example:

{
    "nrf-connect.taskBindings": {
    "flash": [
      {
        "taskName": "My custom flash",
        "buildConfigs": [
          "build",
          "${workspaceFolder}/hello_world/build_1"
          "${workspaceFolder}/samples/bluetooth/perihperal_hids/build",
        ]
      }
    ]
  }
}

With this configuration, the My custom flash task will only be executed if the path of the active build matches the one that is listed in the buildConfigs property.

Note

The buildConfigs property is optional. If this property is not defined, then the binding will apply to all configurations.

Example of multiple tasks

You can bind multiple tasks to a build configuration. For example:

{
    "nrf-connect.taskBindings": {
        "build": [
            { "taskName": "My custom build" },
            { "taskName": "Staging build", "buildConfigs": ["build"] },
            { "taskName": "Release build", "buildConfigs": ["build"] },
        ]
    }
}

In this instance, three tasks have been bound to the build build configuration. The My custom build task was bound implicitly since no builds were declared in the binding, and the remaining two were bound by explicitly naming the build build configuration. When multiple tasks are bound, you will be given a choice of which to execute when you run the action.

Examples of custom task types

You can use the nrf-connect-build and nrf-connect-flash task types for building and flashing a build configuration, respectively.

For example, the following task.json file includes custom nrf-connect-build and nrf-connect-flash types for simplifying the building and flashing process of an nRF52840 DK using some of the accepted parameters:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "nrf-connect-build",
            "config": "${workspaceFolder:hello_world}\\build_nrf52840",
            "runCmake": false,
            "problemMatcher": [
                "$gcc",
                "$cmake",
                "$kconfig",
                "$kconfig_syntax",
                "$kconfig_syntax_files",
                "$dts",
                "$dts_syntax"
            ],
            "group": "build",
            "label": "nRF Connect: Build build_nrf52840 (active)"
        },
        {
            "type": "nrf-connect-flash",
            "config": "${workspaceFolder:hello_world}\\build_nrf52840",
            "snr": "683888634",
            "erase": false,
            "problemMatcher": [],
            "label": "nRF Connect: Flash build_nrf52840 (active)"
        }
    ]
}

Application-specific flash options

If required, you can configure applications with specific flash options. These options will be applied to all flash commands run through the UI that target that application.

The available options are as follows:

  • softreset - if true, it applies the --softreset argument using reset instead of pin reset.
  • skipBuild - if true, it skips the build step before flashing to the device.

To apply these options, open your VS Code settings.json file and create the following entry, customizing it to your needs:

{
    "nrf-connect.applicationOptions": {
        "/path/to/your/application": {
            "flash": {
                "softreset": true,
                "skipBuild": true
            }
        }
    }
}