documentation updates for variable substitution (#4870)

Author: Omotola

CHANGELOG.md

@@ -23,6 +23,7 @@ Features:
 - Add `cmake.outlineViewType` setting to toggle the Project Outline between a flat list view and the prior hierarchical tree view that shows each CMake project separately. [#3799](https://github.com/microsoft/vscode-cmake-tools/issues/3799) [#4538](https://github.com/microsoft/vscode-cmake-tools/pull/4538) [@ar1m4n](https://github.com/ar1m4n)
 
 Improvements:
+- Clarify variable substitution scope in docs for `settings.json` vs generic VS Code `tasks.json`/`launch.json`, including when to use `${command:cmake.*}` and why `${buildKit}`, `${generator}`, and `${config:cmake.configureArgs}` may not expand as expected in tasks. [#4010](https://github.com/microsoft/vscode-cmake-tools/issues/4010)
 - Improve CMake syntax highlighting: extend variable recognition with compiler/toolchain families and add scoped property command colorization for `set_property`, `get_property`, `set_target_properties`, and related commands. [#4527](https://github.com/microsoft/vscode-cmake-tools/pull/4527) [@pboettch](https://github.com/pboettch)
 - Run tests sequentially in alphabetical order (matching the Test Explorer display order) when `cmake.ctest.allowParallelJobs` is disabled. [#4829](https://github.com/microsoft/vscode-cmake-tools/issues/4829)
 - Document how to configure `cmake.debugConfig.visualizerFile` to use custom Natvis files with quick debugging, without requiring a `launch.json`. [#4616](https://github.com/microsoft/vscode-cmake-tools/issues/4616)

docs/cmake-settings.md

@@ -104,7 +104,22 @@ Options that support substitution, in the table below, allow variable references
 
 ## Variable substitution
 
-Some settings support the replacement of special values in their string value by using a `${variable}` syntax. The following built-in variables are expanded:
+Some settings support the replacement of special values in their string value by using a `${variable}` syntax.
+
+### Where substitution works
+
+Use this quick rule to avoid confusion:
+
+- CMake Tools `${...}` variables in this section (for example `${buildKit}` and `${generator}`) are expanded only when CMake Tools reads supported `cmake.*` settings from `settings.json`.
+- Generic VS Code `tasks.json` and `launch.json` fields are resolved by VS Code, not by CMake Tools. In those fields, use VS Code variables (for example `${workspaceFolder}`) or command substitutions such as `${command:cmake.buildKit}`.
+- `${config:cmake.*}` in `tasks.json`/`launch.json` returns the raw setting value. It does not apply a second CMake Tools substitution pass.
+
+Example:
+
+- In a shell task command, `${buildKit}` and `${generator}` are not expanded.
+- In a shell task command, `${command:cmake.buildKit}` is expanded.
+
+The following built-in variables are expanded in supported `cmake.*` settings only. None of these are expanded in generic VS Code shell or process task commands. Use the `${command:cmake.*}` forms listed under [Command substitution](#command-substitution) for those contexts.
 
 | Variable | Expansion |
 |---------|---------|
@@ -136,7 +151,9 @@ Variant options are expanded using the `${variant:VARIANTNAME}` syntax, where th
 
 ### Command substitution
 
-CMake Tools can expand VS Code commands. For example, you can expand the path to the launch target by using the syntax `${command:cmake.launchTargetPath}`
+CMake Tools can expand VS Code commands. For example, you can expand the path to the launch target by using the syntax `${command:cmake.launchTargetPath}`.
+
+This form is the recommended way to get CMake Tools values in generic `tasks.json` or `launch.json` fields.
 
 Be careful with long-running commands because it isn't specified when, or how many times, CMake Tools will execute a command for a given expansion.
 

docs/tasks.md

@@ -3,6 +3,18 @@ You can create a configure task from the VS Code command pallette by running the
 
 ![Configure a task](images/configure_task.png)
 
+## Variable substitution in `tasks.json`
+
+When authoring generic VS Code shell/process tasks, `${buildKit}` and `${generator}` are not expanded because those are CMake Tools setting substitutions, not VS Code task variables.
+
+Use command substitutions in `tasks.json` instead:
+
+- `${command:cmake.buildKit}` for the active kit name.
+- `${command:cmake.buildType}` for the active build type.
+- `${command:cmake.tasksBuildCommand}` for a full CMake build command.
+
+If you use `${config:cmake.configureArgs}` in `tasks.json`, VS Code returns the configured value as-is. CMake Tools substitution is not applied again in that context.
+
 By selecting "CMake: configure" template, if you are not using presets, this task will be generated in `tasks.json` file: