Binding custom tasks to actions¶

The extension lets you customize tasks assigned to the Build and Flash actions. 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
Pristine Build
Flash
Erase and Flash to Board

Bindings created using this interface are stored in the nrf-connect.taskBindings property. You can modify this property manually, which can be easier if you have many bindings or a complicated setup.

Binding tasks to actions from GUI¶

The extension's GUI allows you to add tasks and the extension automatically updates the properties in the related setting files.

How to bind tasks¶

To bind a task to an action:

Hover your cursor over Build or Flash from the Actions View.
Click on the More actions... button (with the three dot icon) that appears to the right.
Click on Bind Task to Action.
A quick-pick menu appears in the Editor.
Click on the action you want to bind.
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.

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.

How to unbind tasks¶

To unbind tasks from an action:

Right-click on Build or Flash.
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 `<file-name>.code-workspace`
Bind Task to Action	`settings.json`	`settings` key in `<file-name>.code-workspace`

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

How to manually add task configuration files¶

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 <file-name>.code-workspace file if you have opened a workspace, but not saved it.

To edit the task configuration file, use the following steps:

Save the workspace.
From the Actions View, click More Actions... > Open Tasks File.
Add the tasks key or edit the settings key to edit the file.

How to add 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:

Option	Description
`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.

Create the following entry, customizing it to your needs:

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

Examples¶

The following examples show some of the common task binding use cases.

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)"
        }
    ]
}