documentation on natvis support (#4858)

Author: Omotola

CHANGELOG.md

@@ -23,6 +23,7 @@ Features:
 
 Improvements:
 - 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)
 - Add `.github/copilot-instructions.md` to ground GitHub Copilot in the repo's architecture and coding conventions.
 - Clicking on a CTest in the Project Outline now navigates to the test source file, matching the existing Test Explorer behavior. [#4773](https://github.com/microsoft/vscode-cmake-tools/issues/4773)
 - Clicking on a CTest unit test in the Test Explorer now navigates to the test source file by matching the test executable to its CMake target's source files. [#4449](https://github.com/microsoft/vscode-cmake-tools/issues/4449)

docs/cmake-settings.md

@@ -42,7 +42,7 @@ Options that support substitution, in the table below, allow variable references
 | `cmake.ctestArgs` | An array of additional arguments to pass to CTest. | `[]` | yes |
 | `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. | `null` (no values) | yes |
+| `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.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 |

docs/debug-launch.md

@@ -57,6 +57,33 @@ Add the following to your `.vscode/settings.json`:
 
 Then run **CMake: Debug Target** from the command palette. CMake Tools will automatically fill in `program`, `cwd`, and `name` from the selected target, and apply your settings on top. Any property recognized by the debug adapter can be added to `cmake.debugConfig`.
 
+### Use Natvis without a launch.json
+
+If you use the cpptools debug adapters (`cppvsdbg` or `cppdbg`), you can provide custom Natvis files directly in `cmake.debugConfig` via `visualizerFile`.
+
+Add this to your `.vscode/settings.json`:
+
+```jsonc
+{
+    "cmake.debugConfig": {
+        "visualizerFile": "${workspaceFolder}/.vscode/types.natvis"
+    }
+}
+```
+
+You can also specify multiple Natvis files:
+
+```jsonc
+{
+    "cmake.debugConfig": {
+        "visualizerFile": [
+            "${workspaceFolder}/.vscode/base.natvis",
+            "${workspaceFolder}/.vscode/project.natvis"
+        ]
+    }
+}
+```
+
 If you omit `type`, CMake Tools falls back to the original behavior: auto-detecting `cppdbg` or `cppvsdbg` from the CMake cache.
 
 ## Debug using a launch.json file