Add support for debugging through GNATemulator

AnthonyLeonardoGracio · AnthonyLeonardoGracio · commit 065e19875c48 · 2025-02-18T09:56:02.000Z
A new 'ada.buildAndDebugGNATemulator' command has been added, with
an associated CodeLens.

For eng/ide/ada_language_server#1375
diff --git a/integration/vscode/ada/src/AdaCodeLensProvider.ts b/integration/vscode/ada/src/AdaCodeLensProvider.ts
@@ -12,6 +12,7 @@ import {
     Uri,
 } from 'vscode';
 import {
+    CMD_BUILD_AND_DEBUG_GNATEMULATOR,
     CMD_BUILD_AND_DEBUG_MAIN,
     CMD_BUILD_AND_RUN_GNATEMULATOR,
     CMD_BUILD_AND_RUN_MAIN,
@@ -77,6 +78,11 @@ export class AdaCodeLensProvider implements CodeLensProvider {
                                         title: '$(run) Run with GNATemulator',
                                         arguments: [document.uri],
                                     }),
+                                    new CodeLens(functions[0].range, {
+                                        command: CMD_BUILD_AND_DEBUG_GNATEMULATOR,
+                                        title: '$(debug-alt-small) Debug with GNATemulator',
+                                        arguments: [document.uri],
+                                    }),
                                 ]);
                             }
 
diff --git a/integration/vscode/ada/src/ExtensionState.ts b/integration/vscode/ada/src/ExtensionState.ts
@@ -69,6 +69,7 @@ export class ExtensionState {
     cachedMains: string[] | undefined;
     cachedExecutables: string[] | undefined;
     cachedAlireTomls: vscode.Uri[] | undefined;
+    cachedDebugServerAddress: string | undefined | null;
     cachedGdb: string | undefined | null = undefined;
 
     private adaTaskProvider?: SimpleTaskProvider;
@@ -82,6 +83,7 @@ export class ExtensionState {
         this.cachedMains = undefined;
         this.cachedExecutables = undefined;
         this.cachedAlireTomls = undefined;
+        this.cachedDebugServerAddress = undefined;
         this.cachedGdb = undefined;
     }
 
@@ -370,6 +372,50 @@ export class ExtensionState {
         return this.cachedTargetPrefix;
     }
 
+    /**
+     * Returns the debug server address that should be used when debugging executables
+     * built for non-native projects.
+     * This checks for the IDE'Program_Host project attribute if {@link forGNATemulator} is
+     * set to false, and the Emulator'Debug_Port otherwise (GNATemulator project attribute).
+     * @param forGNATemulator - Set it to true to retrieve the debug server address that should
+     * be used by GNATemulator.
+     * @returns the debug server address, as a string (e.g: 'localhost:1234')
+     */
+    public async getDebugServerAddress(forGNATemulator = false): Promise<string | null> {
+        type AttributeID = {
+            name: string;
+            package: string;
+        };
+
+        if (this.cachedDebugServerAddress === undefined) {
+            const attrID: AttributeID = {
+                name: forGNATemulator ? 'Debug_Port' : 'Program_Host',
+                package: forGNATemulator ? 'Emulator' : 'IDE',
+            };
+            try {
+                const debugServerAddress = (await this.getProjectAttributeValue(
+                    attrID.name,
+                    attrID.package,
+                )) as string;
+                logger.info(`Got Project.${attrID.package}.${attrID.name} = ${debugServerAddress}`);
+                this.cachedDebugServerAddress = forGNATemulator
+                    ? `localhost:${debugServerAddress}`
+                    : debugServerAddress;
+                logger.info(`Computed debug server address: ${this.cachedDebugServerAddress}`);
+            } catch (err) {
+                const errMessage =
+                    err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+                logger.warn(
+                    `Failed to get Project.${attrID.package}.${attrID.name}: ${errMessage}`,
+                );
+                logger.warn('Assuming there is no debug server address');
+                this.cachedDebugServerAddress = null;
+            }
+        }
+
+        return this.cachedDebugServerAddress;
+    }
+
     /**
      * @returns the full path of the main project file from the ALS
      */
diff --git a/integration/vscode/ada/src/commands.ts b/integration/vscode/ada/src/commands.ts
@@ -23,6 +23,9 @@ import {
     isFromWorkspace,
     workspaceTasksFirst,
     getBuildAndRunTaskName,
+    getRunGNATemulatorTaskName,
+    getBuildTaskName,
+    runTaskAndGetResult,
 } from './taskProviders';
 import { createHelloWorldProject, walkthroughStartDebugging } from './walkthrough';
 import { loadGnatCoverageReport } from './gnattest';
@@ -55,6 +58,16 @@ export const CMD_BUILD_AND_DEBUG_MAIN = 'ada.buildAndDebugMain';
  */
 export const CMD_BUILD_AND_RUN_GNATEMULATOR = 'ada.buildAndRunGNATemulator';
 
+/**
+ * Identifier for a hidden command used for building and debugging a project main,
+ * using GNATemulator.
+ * The command accepts a parameter which is the URI of the main source file.
+ * It is triggered by CodeLenses provided by the extension.
+ *
+ * @see {@link buildAndDebugSpecifiedMain}
+ */
+export const CMD_BUILD_AND_DEBUG_GNATEMULATOR = 'ada.buildAndDebugGNATemulator';
+
 /**
  * Identifier for a hidden command that returns an array of strings constituting
  * the -P and -X project and scenario arguments.
@@ -155,7 +168,12 @@ export function registerCommands(context: vscode.ExtensionContext, clients: Exte
             buildAndRunMainWithGNATemulator,
         ),
     );
-
+    context.subscriptions.push(
+        vscode.commands.registerCommand(
+            CMD_BUILD_AND_DEBUG_GNATEMULATOR,
+            buildAndDebugSpecifiedMainWithGNATemulator,
+        ),
+    );
     context.subscriptions.push(
         vscode.commands.registerCommand(CMD_GPR_PROJECT_ARGS, gprProjectArgs),
     );
@@ -635,19 +653,25 @@ async function buildAndRunMainWithGNATemulator(main: vscode.Uri): Promise<void>
 
 /**
  * This is a command handler that builds the main given as parameter and starts
- * a debug session on that main.  If the given URI does not match one of the
- * project Mains an error is displayed.
+ * a debug session on that main, running GNATemulator in debug mode before when
+ * asked.
+ * If the given URI does not match one of the project Mains an error is displayed.
  *
  * @param main - a URI of a document
+ * @param useGNATemulator - whether the main should be ran through GNATemulator
  */
-async function buildAndDebugSpecifiedMain(main: vscode.Uri): Promise<void> {
+async function buildAndDebugSpecifiedMain(
+    main: vscode.Uri,
+    useGNATemulator: boolean = false,
+): Promise<void> {
     function isMatchingConfig(cfg: vscode.DebugConfiguration, configToMatch: AdaConfig): boolean {
         return cfg.type == configToMatch.type && cfg.name == configToMatch.name;
     }
 
     const wsFolder = vscode.workspace.getWorkspaceFolder(main);
     const adaMain = await findAdaMain(main.fsPath);
     const target = await adaExtState.getTargetPrefix();
+    const debugServerAddress = await adaExtState.getDebugServerAddress(useGNATemulator);
     if (adaMain) {
         /**
          * The vscode API doesn't provide a way to list both automatically
@@ -657,7 +681,7 @@ async function buildAndDebugSpecifiedMain(main: vscode.Uri): Promise<void> {
          * the given main URI.
          */
         // Create a launch config for this main to help with matching
-        const configToMatch = initializeConfig(adaMain, target);
+        const configToMatch = initializeConfig(adaMain, target, debugServerAddress);
         logger.debug('Debug config to match:\n' + JSON.stringify(configToMatch, null, 2));
 
         let matchingConfig = undefined;
@@ -683,6 +707,38 @@ async function buildAndDebugSpecifiedMain(main: vscode.Uri): Promise<void> {
 
         if (matchingConfig) {
             logger.debug('Found matching config: ' + JSON.stringify(matchingConfig, null, 2));
+
+            // Trying to debug via GNATemulator: run the main via GNATemulator in debug mode
+            // before starting the debug session
+            if (useGNATemulator) {
+                const buildTaskName = getBuildTaskName(adaMain);
+                const buildTasks = await getTasksWithPrefix(buildTaskName);
+                if (buildTasks.length === 1) {
+                    const execStatus: number | undefined = await runTaskAndGetResult(buildTasks[0]);
+                    if (execStatus != 0) {
+                        const errorMsg = `Failed to build executable before launching GNATemulator`;
+                        logger.error(errorMsg);
+                        return;
+                    }
+                    logger.debug('Running GNATemulator before starting the debug configuration...');
+                    const runGNATemulatorTaskName = getRunGNATemulatorTaskName(adaMain, true);
+                    const runGNATemulatorForDebugTasks =
+                        await getTasksWithPrefix(runGNATemulatorTaskName);
+
+                    if (runGNATemulatorForDebugTasks.length < 1) {
+                        const errorMsg = `Could not find '${runGNATemulatorTaskName}' task`;
+                        logger.error(errorMsg);
+                        void vscode.window.showErrorMessage(errorMsg, { modal: true });
+                        return;
+                    }
+                    await vscode.tasks.executeTask(runGNATemulatorForDebugTasks[0]);
+                } else {
+                    const errorMsg = `Could not find '${buildTaskName}' task`;
+                    void vscode.window.showErrorMessage(errorMsg, { modal: true });
+                    logger.error(errorMsg);
+                }
+            }
+
             const success = await vscode.debug.startDebugging(wsFolder, matchingConfig);
             if (!success) {
                 void vscode.window.showErrorMessage(
@@ -706,6 +762,17 @@ async function buildAndDebugSpecifiedMain(main: vscode.Uri): Promise<void> {
     }
 }
 
+/**
+ * This is a command handler that builds the main given as parameter and starts
+ * a debug session on that main, with GNATemulator.
+ * If the given URI does not match one of the project Mains an error is displayed.
+ *
+ * @param main - a URI of a document
+ */
+async function buildAndDebugSpecifiedMainWithGNATemulator(main: vscode.Uri): Promise<void> {
+    await buildAndDebugSpecifiedMain(main, true);
+}
+
 /**
  * @returns an array of -P and -X project and scenario command lines arguments
  * for use with GPR-based tools.
diff --git a/integration/vscode/ada/src/debugConfigProvider.ts b/integration/vscode/ada/src/debugConfigProvider.ts
@@ -2,7 +2,7 @@ import assert from 'assert';
 import * as vscode from 'vscode';
 import { adaExtState } from './extension';
 import { AdaMain, getAdaMains, getProjectFile, getProjectFileRelPath } from './helpers';
-import { BUILD_PROJECT_TASK_NAME, getBuildTaskName } from './taskProviders';
+import { getBuildTaskName } from './taskProviders';
 
 export const ADA_DEBUG_BACKEND_TYPE = 'cppdbg';
 
@@ -22,7 +22,9 @@ export interface AdaConfig extends vscode.DebugConfiguration {
         ignoreFailures: boolean;
     }[];
     processId?: string;
+    preLaunchTask?: string;
     miDebuggerPath?: string;
+    miDebuggerServerAddress?: string;
 }
 
 export const adaDynamicDebugConfigProvider = {
@@ -32,8 +34,9 @@ export const adaDynamicDebugConfigProvider = {
     ): Promise<AdaConfig[]> {
         const mains = await getAdaMains();
         const target = await adaExtState.getTargetPrefix();
+        const debugServerAddress = await adaExtState.getDebugServerAddress();
         const configs: AdaConfig[] = mains.flatMap((m) => {
-            return [initializeConfig(m, target), createAttachConfig(m, target)];
+            return [initializeConfig(m, target, debugServerAddress), createAttachConfig(m, target)];
         });
         if (configs.length == 0) {
             /**
@@ -116,12 +119,22 @@ export function initializeDebugging(ctx: vscode.ExtensionContext): {
  * @param name - the full name of the configuration (optional). If provided,
  * this name short-circuits the automatic naming based on the 'main' or the
  * 'program' parameter.
+ * @param debugServerAddress - the debug server address that should be used by the debugger
+ * for remote debugging (equalivalent of 'target remote <debugServerAddress>' command for GDB).
+ * Set it to null to debug the program directly on the host.
  * @returns an AdaConfig
  */
-export function initializeConfig(main: AdaMain, target: string, name?: string): AdaConfig {
+export function initializeConfig(
+    main: AdaMain,
+    target: string,
+    debugServerAddress: string | null,
+    name?: string,
+): AdaConfig {
+    const preLaunchTask = getBuildTaskName(main);
+
     // TODO it would be nice if this and the package.json configuration snippet
     // were the same.
-    const config: AdaConfig = {
+    let config: AdaConfig = {
         type: ADA_DEBUG_BACKEND_TYPE,
         name: name ?? (main ? `Ada: Debug main - ${main.mainRelPath()}` : 'Ada: Debugger Launch'),
         request: 'launch',
@@ -133,11 +146,15 @@ export function initializeConfig(main: AdaMain, target: string, name?: string):
         externalConsole: false,
         args: [],
         MIMode: 'gdb',
-        preLaunchTask: main ? getBuildTaskName(main) : BUILD_PROJECT_TASK_NAME,
+        preLaunchTask: preLaunchTask,
         setupCommands: setupCmd,
         miDebuggerPath: adaExtState.getOrFindGdb(target),
     };
 
+    if (debugServerAddress) {
+        config = { ...config, miDebuggerServerAddress: debugServerAddress };
+    }
+
     return config;
 }
 
@@ -227,8 +244,9 @@ export class AdaInitialDebugConfigProvider implements vscode.DebugConfigurationP
         } else {
             const main = await getOrAskForProgram();
             const target = await adaExtState.getTargetPrefix();
+            const debugServerAddress = await adaExtState.getDebugServerAddress();
             if (main) {
-                return initializeConfig(main, target);
+                return initializeConfig(main, target, debugServerAddress);
             }
         }
 
diff --git a/integration/vscode/ada/src/taskProviders.ts b/integration/vscode/ada/src/taskProviders.ts
