Allow custom debug adapter type in cmake.debugConfig (#4818)

* Initial plan

* feat: allow custom debug adapter type in cmake.debugConfig

When `type` is specified in `cmake.debugConfig`, automatic debugger
detection from the CMake cache is skipped. Instead, a minimal base
configuration is built from the target (program, cwd, name) and
the user's full configuration is overlaid. This enables using any
debug adapter (e.g., codelldb, lldb) with arbitrary properties.

The `CppDebugConfiguration` interface now accepts `type` and
arbitrary additional properties. The `cmake.debugConfig` JSON
schema adds `type` and `additionalProperties: true`.

Fixes #4050

Co-authored-by: Omotola <[email protected]>

* refactor: exclude program from userConfig before Object.assign

Address code review feedback by destructuring program out of
userConfig before overlay, preventing the fragile double-assignment
pattern.

Co-authored-by: Omotola <[email protected]>

* Re-add debug property and update documentation

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Omotola <[email protected]>
Co-authored-by: Omotola <[email protected]>

Author: Copilot

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 1.23
 
 Features:
+- Allow specifying a custom debug adapter type in `cmake.debugConfig` via the `type` property. When set, automatic debugger detection is skipped and any debug adapter (e.g., `codelldb`, `lldb`) can be used with arbitrary configuration properties. [#4818](https://github.com/microsoft/vscode-cmake-tools/pull/4818)
 - Add `${cmake.testEnvironment}` placeholder for launch.json that resolves to the CTest `ENVIRONMENT` test property, and automatically include CTest environment variables when debugging tests without a launch configuration. [#4572](https://github.com/microsoft/vscode-cmake-tools/issues/4572) [#4821](https://github.com/microsoft/vscode-cmake-tools/pull/4821)
 - Add "Delete Build Directory and Reconfigure" command that removes the entire build directory before reconfiguring, ensuring a completely clean state. [#4826](https://github.com/microsoft/vscode-cmake-tools/pull/4826)
 - Add `cmake.shell` setting to route CMake/CTest/CPack subprocess invocations through a custom shell (e.g., Git Bash, MSYS2), enabling embedded toolchains that require POSIX path translation on Windows. [#1750](https://github.com/microsoft/vscode-cmake-tools/issues/1750)

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

@@ -30,7 +30,7 @@ From there, you can press the play button by the `Launch` node to run it in term
 CMake Tools lets you start a debugger on a target without creating a `launch.json`.
 
 > **Note:**
-> Only the debugger from Microsoft's `vscode-ms-vscode.cpptools` extension supports quick-debugging. See [Debug using a launch.json file](#debug-using-a-launchjson-file), below, for information about `launch.json` and using other debuggers.
+> By default, quick-debugging auto-detects the debugger from the CMake cache and uses Microsoft's `vscode-ms-vscode.cpptools` debug adapters (`cppdbg` / `cppvsdbg`). To use a different debug adapter, see [Customize the debug adapter](#customize-the-debug-adapter) below.
 
 Start a debugging session on the active target by running the *CMake: Debug* command from the VS Code command palette, by selecting the Debug button in the status bar or CMake Tools sidebar Project Status View, or by pressing the keyboard shortcut (the default is **Shift+F5**).
 
@@ -39,6 +39,26 @@ Start a debugging session on the active target by running the *CMake: Debug* com
 > **Note:**
 > Quick-debugging does not let you specify program arguments or other debugging options. See the next section for more options.
 
+## Customize the debug adapter
+
+You can use any debug adapter with CMake Tools quick-debugging by setting the `type` property in the `cmake.debugConfig` setting. When `type` is specified, CMake Tools skips automatic debugger detection and builds a minimal launch configuration from the selected target, then merges in all properties from `cmake.debugConfig`. This lets you use adapters like `lldb`, `codelldb`, or any other installed debug extension without creating a `launch.json`.
+
+Add the following to your `.vscode/settings.json`:
+
+```jsonc
+{
+    "cmake.debugConfig": {
+        "type": "lldb",          // any installed debug adapter type
+        "request": "launch",
+        "stopOnEntry": false
+    }
+}
+```
+
+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`.
+
+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
 
 You can specify the working directory or command line arguments for debugging, or use another debugger than the one included with Microsoft's `vscode-ms-vscode.cpptools`, by creating a `launch.json` file.

package.json

@@ -2753,7 +2753,12 @@
         "cmake.debugConfig": {
           "type": "object",
           "description": "%cmake-tools.configuration.cmake.debugConfig.description%",
+          "additionalProperties": true,
           "properties": {
+            "type": {
+              "type": "string",
+              "markdownDescription": "%cmake-tools.configuration.cmake.debugConfig.type.description%"
+            },
             "symbolSearchPath": {
               "type": "string",
               "description": "%cmake-tools.configuration.cmake.debugConfig.symbolSearchPath.description%"

package.nls.json

@@ -217,7 +217,8 @@
         ]
     },
     "cmake-tools.configuration.cmake.additionalBuildProblemMatchers.code": "The capture group index for an optional diagnostic code.",
-    "cmake-tools.configuration.cmake.debugConfig.description": "The debug configuration to use when debugging a target.",
+    "cmake-tools.configuration.cmake.debugConfig.description": "The debug configuration to use when debugging a target. When `type` is specified, the auto-detected debugger configuration is skipped and only a minimal base configuration (program, cwd, name) is generated from the target. All other properties are applied from this setting, allowing full control over the debug launch configuration for any debug adapter.",
+    "cmake-tools.configuration.cmake.debugConfig.type.description": "The debug adapter type to use (e.g., `cppdbg`, `cppvsdbg`, `lldb`, `codelldb`). When set, skips the automatic debugger detection from the CMake cache and uses this type directly. Any additional properties required by the debug adapter can be added to `#cmake.debugConfig#`.",
     "cmake-tools.configuration.cmake.debugConfig.symbolSearchPath.description": "Visual Studio debugger symbol search paths.",
     "cmake-tools.configuration.cmake.debugConfig.additionalSOLibSearchPath.description": "Paths for GDB or LLDB to search for .so files.",
     "cmake-tools.configuration.cmake.debugConfig.externalConsole.description": "Launch an external console for the program.",

src/cmakeProject.ts

@@ -2611,29 +2611,48 @@ export class CMakeProject {
         };
 
         let debugConfig;
-        try {
-            const cache = await CMakeCache.fromPath(drv.cachePath);
-            debugConfig = await debuggerModule.getDebugConfigurationFromCache(cache, target, process.platform,
-                this.workspaceContext.config.debugConfig?.MIMode,
-                this.workspaceContext.config.debugConfig?.miDebuggerPath);
-        } catch (error: any) {
-            void vscode.window
-                .showErrorMessage(error.message, {
-                    title: localize('debugging.documentation.button', 'Debugging documentation'),
-                    isLearnMore: true
-                })
-                .then(item => {
-                    if (item && item.isLearnMore) {
-                        open('https://vector-of-bool.github.io/docs/vscode-cmake-tools/debugging.html');
-                    }
-                });
-            return null;
-        }
+        const userConfig = this.workspaceContext.config.debugConfig;
+        if (userConfig?.type) {
+            // User specified a custom debug adapter type — skip auto-detection
+            // and build a minimal base config from the target. Properties from
+            // userConfig are merged on top, so any base property can be overridden.
+            debugConfig = {
+                type: userConfig.type,
+                name: `Debug ${testName}`,
+                request: 'launch',
+                program: testInfo.program,
+                cwd: path.dirname(testInfo.program),
+                args: [] as string[]
+            };
+            Object.assign(debugConfig, userConfig);
+        } else {
+            try {
+                const cache = await CMakeCache.fromPath(drv.cachePath);
+                debugConfig = await debuggerModule.getDebugConfigurationFromCache(cache, target, process.platform,
+                    userConfig?.MIMode,
+                    userConfig?.miDebuggerPath);
+            } catch (error: any) {
+                void vscode.window
+                    .showErrorMessage(error.message, {
+                        title: localize('debugging.documentation.button', 'Debugging documentation'),
+                        isLearnMore: true
+                    })
+                    .then(item => {
+                        if (item && item.isLearnMore) {
+                            open('https://vector-of-bool.github.io/docs/vscode-cmake-tools/debugging.html');
+                        }
+                    });
+                return null;
+            }
 
-        if (debugConfig === null) {
-            log.error(localize('failed.to.generate.debugger.configuration', 'Failed to generate debugger configuration'));
-            void vscode.window.showErrorMessage(localize('unable.to.generate.debugging.configuration', 'Unable to generate a debugging configuration.'));
-            return null;
+            if (debugConfig === null) {
+                log.error(localize('failed.to.generate.debugger.configuration', 'Failed to generate debugger configuration'));
+                void vscode.window.showErrorMessage(localize('unable.to.generate.debugging.configuration', 'Unable to generate a debugging configuration.'));
+                return null;
+            }
+
+            // Add debug configuration from settings
+            Object.assign(debugConfig, userConfig);
         }
 
         // Add test arguments and working directory
@@ -2642,10 +2661,6 @@ export class CMakeProject {
             debugConfig.cwd = testInfo.workingDirectory;
         }
 
-        // Add debug configuration from settings
-        const userConfig = this.workspaceContext.config.debugConfig;
-        Object.assign(debugConfig, userConfig);
-
         // Merge CTest ENVIRONMENT properties into the debug environment
         const testEnvVars = util.makeDebuggerEnvironmentVars(testInfo.environment);
         const combinedEnvVars = [...testEnvVars, ...(debugConfig.environment ?? [])];
@@ -3209,36 +3224,52 @@ export class CMakeProject {
         }
 
         let debugConfig;
-        try {
-            const cache = await CMakeCache.fromPath(drv.cachePath);
-            debugConfig = await debuggerModule.getDebugConfigurationFromCache(cache, targetExecutable, process.platform,
-                this.workspaceContext.config.debugConfig?.MIMode,
-                this.workspaceContext.config.debugConfig?.miDebuggerPath);
-            log.debug(localize('debug.configuration.from.cache', 'Debug configuration from cache: {0}', JSON.stringify(debugConfig)));
-        } catch (error: any) {
-            void vscode.window
-                .showErrorMessage(error.message, {
-                    title: localize('debugging.documentation.button', 'Debugging documentation'),
-                    isLearnMore: true
-                })
-                .then(item => {
-                    if (item && item.isLearnMore) {
-                        open('https://vector-of-bool.github.io/docs/vscode-cmake-tools/debugging.html');
-                    }
-                });
-            log.debug(localize('problem.getting.debug', 'Problem getting debug configuration from cache.'), error);
-            return null;
-        }
+        const userConfig = this.workspaceContext.config.debugConfig;
+        if (userConfig?.type) {
+            // User specified a custom debug adapter type — skip auto-detection
+            // and build a minimal base config from the target. Properties from
+            // userConfig are merged on top, so any base property can be overridden.
+            debugConfig = {
+                type: userConfig.type,
+                name: `Debug ${targetExecutable.name}`,
+                request: 'launch',
+                program: targetExecutable.path,
+                cwd: targetExecutable.debuggerWorkingDirectory || path.dirname(targetExecutable.path),
+                args: [] as string[]
+            };
+            Object.assign(debugConfig, userConfig);
+            log.debug(localize('debug.configuration.from.settings', 'Debug configuration from user settings: {0}', JSON.stringify(debugConfig)));
+        } else {
+            try {
+                const cache = await CMakeCache.fromPath(drv.cachePath);
+                debugConfig = await debuggerModule.getDebugConfigurationFromCache(cache, targetExecutable, process.platform,
+                    userConfig?.MIMode,
+                    userConfig?.miDebuggerPath);
+                log.debug(localize('debug.configuration.from.cache', 'Debug configuration from cache: {0}', JSON.stringify(debugConfig)));
+            } catch (error: any) {
+                void vscode.window
+                    .showErrorMessage(error.message, {
+                        title: localize('debugging.documentation.button', 'Debugging documentation'),
+                        isLearnMore: true
+                    })
+                    .then(item => {
+                        if (item && item.isLearnMore) {
+                            open('https://vector-of-bool.github.io/docs/vscode-cmake-tools/debugging.html');
+                        }
+                    });
+                log.debug(localize('problem.getting.debug', 'Problem getting debug configuration from cache.'), error);
+                return null;
+            }
 
-        if (debugConfig === null) {
-            log.error(localize('failed.to.generate.debugger.configuration', 'Failed to generate debugger configuration'));
-            void vscode.window.showErrorMessage(localize('unable.to.generate.debugging.configuration', 'Unable to generate a debugging configuration.'));
-            return null;
-        }
+            if (debugConfig === null) {
+                log.error(localize('failed.to.generate.debugger.configuration', 'Failed to generate debugger configuration'));
+                void vscode.window.showErrorMessage(localize('unable.to.generate.debugging.configuration', 'Unable to generate a debugging configuration.'));
+                return null;
+            }
 
-        // Add debug configuration from settings.
-        const userConfig = this.workspaceContext.config.debugConfig;
-        Object.assign(debugConfig, userConfig);
+            // Add debug configuration from settings.
+            Object.assign(debugConfig, userConfig);
+        }
 
         const launchEnv = await this.getTargetLaunchEnvironment(drv, debugConfig.environment);
         debugConfig.environment = util.makeDebuggerEnvironmentVars(launchEnv);

src/debug/debugger.ts

@@ -29,6 +29,7 @@ export interface VSCodeDebugConfiguration extends CppDebugConfiguration {
  * interface that maps to cmake.debugConfig.
  */
 export interface CppDebugConfiguration {
+    type?: string;
     symbolSearchPath?: string;
     additionalSOLibSearchPath?: string;
     externalConsole?: boolean;
@@ -46,6 +47,7 @@ export interface CppDebugConfiguration {
     launchCompleteCommand?: string;
     dumpPath?: string;
     coreDumpPath?: string;
+    [key: string]: any;
 }
 
 export interface DebuggerLogging {