Rework the integration of debug configurations

* Do not create a launch.json until the User asks for a debug session
* Do not expose hidden ada.initDebugFile command to Users
* Rename ada.initDebugFile command to more meaningful ada.askForProgram
* Do not use the debugger type "cppdbg" in package.json because it
  clashes with the existing CPP debugger. Instead we use the debugger
  type 'ada' in package.json but we never use it in actual resolved
  configurations.
* Do not provide a JSON schema for debug configurations since the CPP
  extension already defines it for the 'cppdbg' type and we don't intend
  to actually use the 'ada' type.
* Set the program field of cppdbg configurations to a full path as
  expected by the C++ debug extension.

Author: eliericha

integration/vscode/ada/package.json

@@ -508,11 +508,6 @@
                 "command": "ada.showGprLSOutput",
                 "title": "Ada: Show GPR Language Server Output",
                 "when": "ADA_PROJECT_CONTEXT"
-            },
-            {
-                "command": "ada.initDebugFile",
-                "title": "Ada: Debug File",
-                "when": "ADA_PROJECT_CONTEXT"
             }
         ],
         "keybindings": [
@@ -589,7 +584,7 @@
         ],
         "debuggers": [
             {
-                "type": "cppdbg",
+                "type": "ada",
                 "label": "Ada",
                 "languages": [
                     "ada",
@@ -599,64 +594,22 @@
                 "when": "ADA_PROJECT_CONTEXT",
                 "configurationSnippets": [
                     {
-                        "label": "Ada Debugger Launch",
+                        "label": "Ada: Debugger Launch",
                         "description": "Launch configuration for Ada debugging.",
                         "body": {
                             "type": "cppdbg",
                             "request": "launch",
-                            "name": "Ada Debugger Launch",
-                            "program": "your-executable-path",
+                            "name": "Ada: Debugger Launch",
+                            "program": "^\"\\${workspaceFolder}/\\${command:ada.askForProgram}\"",
                             "args": [],
-                            "cwd": "${workspaceFolder}",
+                            "cwd": "^\"\\${workspaceFolder}\"",
                             "stopAtEntry": false,
-                            "preLaunchTask": "your-prelaunch-task"
+                            "preLaunchTask": "ada: Build current project"
                         }
                     }
                 ],
-                "configurationAttributes": {
-                    "launch": {
-                        "required": [
-                            "program"
-                        ],
-                        "properties": [
-                            {
-                                "program": {
-                                    "type": "string",
-                                    "description": "Path to program executable.",
-                                    "default": "${command:AskForProgram}"
-                                },
-                                "cwd": {
-                                    "type": "string",
-                                    "description": "The working directory of the target.",
-                                    "default": "${workspaceRoot}"
-                                },
-                                "stopAtEntry": {
-                                    "type": "boolean",
-                                    "description": "If true, the debugger should stop at the entrypoint of the target.",
-                                    "default": false
-                                },
-                                "args": {
-                                    "description": "Arguments passed to the program entrypoint",
-                                    "items": {
-                                        "type": "string"
-                                    },
-                                    "type": [
-                                        "array",
-                                        "string"
-                                    ],
-                                    "default": []
-                                },
-                                "preLaunchTask": {
-                                    "type": "string",
-                                    "description": "The build task to launch before debugging",
-                                    "default": "ada: Build current project"
-                                }
-                            }
-                        ]
-                    }
-                },
                 "variables": {
-                    "AskForProgram": "ada.initDebugFile"
+                    "AskForProgram": "ada.askForProgram"
                 }
             }
         ]

integration/vscode/ada/src/commands.ts

@@ -1,9 +1,9 @@
 import * as vscode from 'vscode';
 import { SymbolKind } from 'vscode';
-import { getEnclosingSymbol } from './gnatTaskProvider';
-import { mainLogChannel } from './extension';
 import { ContextClients } from './clients';
 import { AdaDebugConfigProvider } from './debugConfigProvider';
+import { mainLogChannel } from './extension';
+import { getEnclosingSymbol } from './gnatTaskProvider';
 
 export function registerCommands(
     context: vscode.ExtensionContext,
@@ -29,9 +29,12 @@ export function registerCommands(
             clients.gprClient.outputChannel.show()
         )
     );
+
+    // This is a hidden command that gets called in the default debug
+    // configuration snippet that gets offered in the launch.json file.
     context.subscriptions.push(
-        vscode.commands.registerCommand('ada.initDebugFile', async () => {
-            const p = await debug.initDebugCmd();
+        vscode.commands.registerCommand('ada.askForProgram', async () => {
+            const p = await debug.askForProgram();
             return p;
         })
     );

integration/vscode/ada/src/debugConfigProvider.ts

@@ -1,5 +1,5 @@
-import * as vscode from 'vscode';
 import * as path from 'path';
+import * as vscode from 'vscode';
 import { ContextClients } from './clients';
 import { getExecutables, getMains } from './helpers';
 
@@ -26,72 +26,62 @@ interface AdaConfig extends vscode.DebugConfiguration {
  * @param clients - the language clients
  * @returns the debug configuration provider
  */
-export async function initializeDebugging(ctx: vscode.ExtensionContext, clients: ContextClients) {
+export function initializeDebugging(ctx: vscode.ExtensionContext, clients: ContextClients) {
+    // Instantiate a DebugConfigProvider for Ada and register it.
     const provider = new AdaDebugConfigProvider(clients);
-    ctx.subscriptions.push(
-        vscode.debug.registerDebugConfigurationProvider(
-            AdaDebugConfigProvider.adaConfigType,
-            provider
-        )
-    );
-
-    const workspaceConfig = vscode.workspace.getConfiguration();
-    const configurations: vscode.DebugConfiguration[] =
-        (workspaceConfig.get('launch.configurations') as vscode.DebugConfiguration[]) || [];
-
-    let status = false;
-    for (const config of configurations) {
-        if (config.name == 'Debug Ada') {
-            status = true;
-            break;
-        }
-    }
 
-    if (!status) {
-        const initialDebugConfiguration = initializeConfig(undefined, '${command:AskForProgram}');
+    // This provider is registered for the 'ada' debugger type. It means that
+    // it is triggered either when a configuration with type 'ada' is launched,
+    // or when the applicable context of the 'ada' debugger type is enabled
+    // (see package.json/debuggers).
+    //
+    // However concretely we never define debug configurations of the type
+    // 'ada'. All the provided configurations use the type 'cppdbg'. This means
+    // that once a 'cppdbg' is declared in the launch.json file, this provider
+    // is no longer called since it is not registered for the type 'cppdbg'.
+    // Moreover, it is somewhat discouraged to register it for the type
+    // 'cppdbg' since that type is provided by another extension.
+    ctx.subscriptions.push(vscode.debug.registerDebugConfigurationProvider('ada', provider));
 
-        configurations.push(initialDebugConfiguration);
+    // TODO it is also possible to register another provider with trigger kind
+    // 'Dynamic', however the role of such a provider is unclear. In practical
+    // experiments it ends up never being called. The above provider is enough
+    // to make it possible to launch debug sessions without a launch.json.
 
-        await workspaceConfig.update(
-            'launch.configurations',
-            configurations,
-            vscode.ConfigurationTarget.Workspace
-        );
-    }
     return provider;
 }
 /**
- * Initialize the GDB debug configuration for an executable,
- * either program or command must be specified
+ * Initialize a debug configuration based on 'cppdbg' for the given executable
+ * if specified. Otherwise the program field includes
+ * ${command:ada.askForProgram} to prompt the User for an executable to debug.
+ *
  * @param program - the executable to debug (optional)
- * @param command - the command to collect the program to debug (optional)
  * @returns an AdaConfig
  */
-function initializeConfig(program?: string, command?: string): AdaConfig {
-    // Get the executable name from the relative path
+function initializeConfig(program?: string): AdaConfig {
+    // TODO it would be nice if this and the package.json configuration snippet
+    // were the same.
     const config: AdaConfig = {
         type: 'cppdbg',
-        name: 'Ada Config',
+        name: 'Ada: Debugger Launch',
         request: 'launch',
         targetArchitecture: process.arch,
         cwd: '${workspaceFolder}',
-        program: 'Ada executable to debug',
+        program: '${workspaceFolder}/${command:ada.askForProgram}',
         stopAtEntry: false,
         externalConsole: false,
         args: [],
         MIMode: 'gdb',
-        // preLaunchTask: 'gpr: Build Executable for File ' + main_name,
         preLaunchTask: 'ada: Build current project',
         setupCommands: setupCmd,
     };
-    if (command) {
-        config.name = 'Debug Ada';
-        config.program = command;
-    } else if (program) {
+
+    if (program) {
         const name = path.basename(program);
-        config.name = 'Debug executable ' + name;
+        config.name = 'Ada: Debug executable - ' + name;
         config.program = program;
     }
+
     return config;
 }
 
@@ -102,19 +92,23 @@ export class AdaDebugConfigProvider implements vscode.DebugConfigurationProvider
     constructor(clients: ContextClients) {
         this.clients = clients;
     }
-    // Provider
+
     async provideDebugConfigurations(
         folder: vscode.WorkspaceFolder | undefined,
         _token?: vscode.CancellationToken | undefined
     ): Promise<vscode.DebugConfiguration[]> {
-        // provide a non-existent debug/launch configuration
-        const config: vscode.DebugConfiguration[] = [];
+        // This method is called when no launch.json exists. The provider
+        // should return a set of configurations to initialize the launch.json
+        // file with.
+        const configs: vscode.DebugConfiguration[] = [];
+
         if (_token?.isCancellationRequested) {
-            return [];
+            return Promise.reject('Cancelled');
         }
+
         if (folder != undefined) {
+            // Offer a list of known Mains from the project
             const execs = await getExecutables(this.clients.adaClient);
-            // Show the option for the user to choose the executable
             const quickpick = execs.map((e) => ({
                 label: vscode.workspace.asRelativePath(e),
                 description: 'Generate the associated configuration',
@@ -123,27 +117,48 @@ export class AdaDebugConfigProvider implements vscode.DebugConfigurationProvider
                 placeHolder: 'Select a program to debug',
             });
             if (selectedProgram) {
-                const configuration = initializeConfig(selectedProgram.label);
-                config.push(configuration);
+                // The cppdbg debug configuration exepects the executable to be
+                // a full path rather than a path relative to the specified
+                // cwd. That is why we include ${workspaceFolder}.
+                const configuration = initializeConfig(
+                    `\${workspaceFolder}/${selectedProgram.label}`
+                );
+                configs.push(configuration);
+            } else {
+                return Promise.reject('Cancelled');
             }
-            return config;
-        } else {
-            return config;
         }
+
+        return configs;
     }
 
     async resolveDebugConfiguration(
         _folder: vscode.WorkspaceFolder | undefined,
         debugConfiguration: vscode.DebugConfiguration,
         _token?: vscode.CancellationToken | undefined
     ): Promise<vscode.DebugConfiguration | undefined> {
-        // resolve a incompleted debug/launch configuration
+        // This method is called when a debug session is being started. The
+        // debug configuration either comes from the launch.json file, or is
+        // empty when no launch.json exists.
+
         if (_token?.isCancellationRequested) {
             return undefined;
         }
+
         if (debugConfiguration.request == 'launch') {
+            // When the given debug configuration has its fields set, it means
+            // that the debug configuration is coming from a launch.json file
+            // and we don't want to alter it. Concretely this never occurs
+            // because we register this provider for the debugger type 'ada'
+            // which we never create in launch.json files. Instead we always
+            // create 'cppdbg' configurations which never go through this
+            // provider.
             return debugConfiguration;
         }
+
+        // We are operating without a launch.json. So we try to determine the
+        // program to debug dynamically. If the current editor matches one of
+        // the Mains of the project, then debug the corresponding executable.
         const file = vscode.window.activeTextEditor?.document.uri.path;
         if (file != undefined) {
             const mains = await getMains(this.clients.adaClient);
@@ -154,33 +169,44 @@ export class AdaDebugConfigProvider implements vscode.DebugConfigurationProvider
                     return config;
                 }
             }
-            const quickpick = mains.map((e) => ({
-                label: vscode.workspace.asRelativePath(e),
-                description: 'Run & Debug',
-                main: e,
-            }));
-            const selectedProgram = await vscode.window.showQuickPick(quickpick, {
-                placeHolder: 'Select a main file',
-            });
-            if (selectedProgram) {
-                const index = mains.indexOf(selectedProgram.main);
-                const configuration = initializeConfig(execs[index]);
-                return configuration;
-            }
         }
+
+        // There is no current file or it matches no known Main of the project,
+        // so we offer all Main in a QuickPicker for the user to choose from.
+        const quickpick = execs.map((e) => ({
+            label: vscode.workspace.asRelativePath(e),
+            description: 'Run & Debug',
+            fullPath: e,
+        }));
+        const selectedProgram = await vscode.window.showQuickPick(quickpick, {
+            placeHolder: 'Select an executable to debug',
+        });
+        if (selectedProgram) {
+            // This is an in-memory configuration that will not be stored. It's
+            // okay to use the full path directly instead of using
+            // ${workspaceFolder}.
+            const configuration = initializeConfig(selectedProgram.fullPath);
+            return configuration;
+        }
+
         return undefined;
     }
 
     /**
-     * Resolves the program path fron the 'Debug Ada' default configuration
-     * @returns the executable path to debug
+     * Consults the project for a list of Mains. If only one is defined, it is
+     * returned immediately. If multiple ones are defines, a QuickPicker is
+     * given to the User to choose and executable to debug or to specify in a
+     * debug configuration.
+     *
+     * @returns the path of the executable to debug relative to the workspace
      */
-    async initDebugCmd(): Promise<string | undefined> {
+    async askForProgram(): Promise<string | undefined> {
         const file = vscode.window.activeTextEditor?.document.uri.path;
         const mains = await getMains(this.clients.adaClient);
         const execs = await getExecutables(this.clients.adaClient);
 
-        if (mains.length == 1) return execs[0];
+        if (execs.length == 1) return vscode.workspace.asRelativePath(execs[0]);
+
         if (file != undefined) {
             for (let i = 0; i < mains.length; i++) {
                 if (file == mains[i]) {
@@ -198,8 +224,9 @@ export class AdaDebugConfigProvider implements vscode.DebugConfigurationProvider
         });
         if (selectedProgram) {
             const index = mains.indexOf(selectedProgram.main);
-            return execs[index];
+            return vscode.workspace.asRelativePath(execs[index]);
         }
+
         return undefined;
     }
 }