Skip to content

Add cmake.launchConfig setting for customizable run configurations #4916

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
hanniavalera wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Add cmake.launchConfig setting for customizable run configurations #4916

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bb32cd6
Add cmake.launchConfig setting for customizable run configurations
hanniavalera Apr 29, 2026
7701ac4
took in feedback
hanniavalera May 1, 2026
36b1c29
fixed bug, we should always fetch all tasks and filter in-memory
hanniavalera May 4, 2026
3b355ca
Merge branch 'main' into dev/hanniavalera/embeddedDbug
hanniavalera May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
Features:
- Add support for the FASTBuild generator (CMake 4.2+). [#4690](https://github.com/microsoft/vscode-cmake-tools/pull/4690)
- Add support for `${workspaceFolder}`, `${workspaceFolder:name}` variables and relative paths in `cmake.exclude` setting for multi-root workspaces. [#4689](https://github.com/microsoft/vscode-cmake-tools/pull/4689)
- Add `cmake.launchConfig` setting to customize "Run Without Debugging"; supports delegating to a VS Code task or running a custom program (e.g., firmware flash tool). [#4904](https://github.com/microsoft/vscode-cmake-tools/issues/4904)

Improvements:
- Improve responsiveness to CMake path changes made by vendor extensions during configure-on-open retry. [#4908](https://github.com/microsoft/vscode-cmake-tools/pull/4908) Contributed by STMicroelectronics
Expand Down
1 change: 1 addition & 0 deletions docs/cmake-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ Options that support substitution, in the table below, allow variable references
| `cmake.ctestDefaultArgs` | Default arguments to pass to CTest. | `["-T", "test", "--output-on-failure"]` | no |
| `cmake.ctestPath` | Path to CTest executable. | `null` | no |
| `cmake.debugConfig`| The debug configuration to use when debugging a target. When `type` is specified, automatic debugger detection is skipped and a custom debug adapter can be used. Additional properties required by the debug adapter can be added freely. See [Debug and launch](debug-launch.md#customize-the-debug-adapter) for examples, including Natvis via `visualizerFile` without a `launch.json`. | `null` (no values) | yes |
| `cmake.launchConfig`| Customize the "Run Without Debugging" command to delegate to a VS Code task or run a custom program (e.g., firmware flash tool, OpenOCD, west). Set to either `task` (a string or `{name, type?}` object) or `program` (with optional `args`, `cwd`, `environment`). Supports `${command:cmake.launchTargetPath}`, `${workspaceFolder}`, and `${env:VAR}` variable substitution. `cmake.buildBeforeRun` and `cmake.launchBehavior` (`reuseTerminal`/`newTerminal`/`breakAndReuseTerminal`) still apply in program mode. **Important:** when set, `cmake.debugConfig.args`, `cwd`, and `environment` are not applied to the launch path (debug-only). A one-time warning is shown if both settings are populated. [#4904](https://github.com/microsoft/vscode-cmake-tools/issues/4904) | `null` | yes |
| `cmake.defaultActiveFolder`| The name of active folder, which be used as default (Only works when `cmake.autoSelectActiveFolder` is disabled). | `""` | no |
| `cmake.defaultVariants` | Override the default set of variants that will be supplied when no variants file is present. See [CMake variants](variants.md). | See package.json | no |
| `cmake.deleteBuildDirOnCleanConfigure` | If `true`, delete build directory during clean configure. | `false` | no |
Expand Down
54 changes: 54 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2943,6 +2943,60 @@
},
"scope": "resource"
},
"cmake.launchConfig": {
"type": "object",
"scope": "resource",
"markdownDescription": "%cmake-tools.configuration.cmake.launchConfig.markdownDescription%",
"additionalProperties": false,
"oneOf": [
{ "required": ["task"] },
{ "required": ["program"] }
],
"properties": {
"task": {
"description": "%cmake-tools.configuration.cmake.launchConfig.task.description%",
"oneOf": [
{ "type": "string" },
{
"type": "object",
"additionalProperties": false,
"required": ["name"],
"properties": {
"name": { "type": "string" },
"type": { "type": "string" }
}
}
]
},
"program": {
"type": "string",
"description": "%cmake-tools.configuration.cmake.launchConfig.program.description%"
},
"args": {
Copy link
Copy Markdown
Collaborator

@gcampbell-msft gcampbell-msft Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do the args and following properties apply to both scenarios of task and program? I imagine that the task itself has these already, how is this handled?

Copy link
Copy Markdown
Contributor Author

@hanniavalera hanniavalera May 4, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They only apply to program mode as VS Code tasks already own those fields. I've tightened the descriptions to say "(ignored in task mode)" and added a defensive log.warning in runLaunchAsTask if a user sets them anyway, so the override is visible without being disruptive.

"type": "array",
"items": { "type": "string" },
"default": [],
"description": "%cmake-tools.configuration.cmake.launchConfig.args.description%"
},
"cwd": {
"type": "string",
"description": "%cmake-tools.configuration.cmake.launchConfig.cwd.description%"
},
"environment": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["name", "value"],
"properties": {
"name": { "type": "string" },
"value": { "type": "string" }
}
},
"description": "%cmake-tools.configuration.cmake.launchConfig.environment.description%"
}
}
},
"cmake.defaultVariants": {
"type": "object",
"$schema": "cmake-tools-schema://schemas/variants-schema.json",
Expand Down
18 changes: 18 additions & 0 deletions package.nls.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,24 @@
"cmake-tools.configuration.cmake.debugConfig.setupCommands.description": "Command to set up gdb or lldb.",
"cmake-tools.configuration.cmake.debugConfig.setupCommands.text.description": "Command to run.",
"cmake-tools.configuration.cmake.debugConfig.setupCommands.description.description": "Description of the command.",
"cmake-tools.configuration.cmake.launchConfig.markdownDescription": "Redirect the **CMake: Run Without Debugging** command (`cmake.launchTarget`) to either a VS Code task from `tasks.json` (`task` mode) or a custom external program (`program` mode). The active CMake target is still built first when `#cmake.buildBeforeRun#` is enabled, and its path is available via `${command:cmake.launchTargetPath}`. When set, this setting **fully replaces** `#cmake.debugConfig#`'s `args`, `cwd`, and `environment` on the launch path; provide equivalents inside `cmake.launchConfig` instead. The debug command (`cmake.debugTarget`) is unaffected. Only one of `task` or `program` may be set. When the delegated task itself depends on a CMake build (e.g. via `dependsOn`), consider setting `#cmake.buildBeforeRun#` to `false` to avoid building twice. When using `program`, the terminal lifecycle follows the `#cmake.launchBehavior#` setting (reuse, break-and-reuse, or new terminal).",
"cmake-tools.configuration.cmake.launchConfig.task.description": "Name of a task from `tasks.json` to run instead of launching the built executable. Accepts either a bare string label or `{ \"name\": \"...\", \"type\": \"...\" }` to disambiguate when multiple providers register tasks with the same name. Mutually exclusive with `program`.",
"cmake-tools.configuration.cmake.launchConfig.program.description": "Path to a custom program to run instead of the built executable. Supports `${command:cmake.launchTargetPath}` and other VS Code variable substitutions. Mutually exclusive with `task`.",
"cmake-tools.configuration.cmake.launchConfig.args.description": "Arguments to pass to the custom `program` (ignored in `task` mode). Each entry is shell-quoted before being sent to the integrated terminal.",
"cmake-tools.configuration.cmake.launchConfig.cwd.description": "Working directory for the custom `program` (ignored in `task` mode). Defaults to the directory of the built executable.",
"cmake-tools.configuration.cmake.launchConfig.environment.description": "Environment variables to set when running the custom `program` (ignored in `task` mode). Array of `{ \"name\": ..., \"value\": ... }` objects, mirroring `cmake.debugConfig.environment`.",
"cmake-tools.launchConfig.task.notFound": "Task '{0}' referenced by cmake.launchConfig was not found.",
"cmake-tools.launchConfig.task.executeFailed": "Failed to execute task \"{0}\" referenced by cmake.launchConfig: {1}",
"cmake-tools.launchConfig.task.ambiguous": "Multiple tasks named '{0}' found; using the first. Specify 'type' in cmake.launchConfig.task to disambiguate.",
"cmake-tools.launchConfig.launching.task": "Launching via task '{0}'",
"cmake-tools.launchConfig.launching.task.withType": "Launching via task '{0}' (type: {1})",
"cmake-tools.launchConfig.launching.program": "Launching custom program '{0}'",
"cmake-tools.launchConfig.debugConfigShadow.message": "cmake.launchConfig is set, so cmake.debugConfig.args, cmake.debugConfig.cwd, and cmake.debugConfig.environment will be ignored on the Run-Without-Debugging path. (cmake.debugConfig still applies when debugging.)",
"cmake-tools.launchConfig.debugConfigShadow.openSettings": "Open Settings",
"cmake-tools.launchConfig.debugConfigShadow.dontShowAgain": "Don't show again",
"cmake-tools.launchConfig.task.ignoredFields": "cmake.launchConfig: args, cwd, and environment are ignored in task mode. These settings only apply when using \"program\".",
"cmake-tools.projectStatus.launchConfig.viaTask": "(via task: {0})",
"cmake-tools.projectStatus.launchConfig.viaProgram": "(via program: {0})",
"cmake-tools.configuration.cmake.defaultVariants.overall.description": "Configure the default variant settings.",
"cmake-tools.configuration.cmake.defaultVariants.buildType.description": "The build type.",
"cmake-tools.configuration.cmake.defaultVariants.buildType.unspecified.long": "Let CMake pick the default build type.",
Expand Down
Loading
Loading