[lldb-dap] Adding a modules explorer to lldb-dap ext.

This creates a very basic module explorer for tracking and displaying loaded modules, reported by lldb-dap for the active debug session.

This includes a basic session tracker that we can use to observe the debug session and collect specific information for additional visualizations in the lldb-dap ext.

Author: ashgti

lldb/tools/lldb-dap/package-lock.json

@@ -30,9 +30,10 @@
   "devDependencies": {
     "@types/node": "^18.19.41",
     "@types/vscode": "1.75.0",
+    "@vscode/debugprotocol": "^1.68.0",
     "@vscode/vsce": "^3.2.2",
-    "prettier-plugin-curly": "^0.3.1",
     "prettier": "^3.4.2",
+    "prettier-plugin-curly": "^0.3.1",
     "typescript": "^5.7.3"
   },
   "activationEvents": [
@@ -763,6 +764,16 @@
           }
         ]
       }
-    ]
+    ],
+    "views": {
+      "debug": [
+        {
+          "id": "lldb-dap.modulesExplorer",
+          "name": "LLDB Modules Explorer",
+          "when": "inDebugMode && debugType == 'lldb-dap'",
+          "icon": "$(symbol-module)"
+        }
+      ]
+    }
   }
 }

lldb/tools/lldb-dap/package.json

@@ -78,7 +78,7 @@ export class LLDBDapConfigurationProvider
     debugConfiguration: vscode.DebugConfiguration,
     token?: vscode.CancellationToken,
   ): Promise<vscode.DebugConfiguration> {
-    let config = vscode.workspace.getConfiguration("lldb-dap.defaults");
+    let config = vscode.workspace.getConfiguration("lldb-dap");
     for (const [key, cfg] of Object.entries(configurations)) {
       if (Reflect.has(debugConfiguration, key)) {
         continue;

lldb/tools/lldb-dap/src-ts/debug-configuration-provider.ts

@@ -0,0 +1,87 @@
+import { DebugProtocol } from "@vscode/debugprotocol";
+import * as vscode from "vscode";
+
+interface EventMap {
+  module: DebugProtocol.ModuleEvent;
+}
+
+function isEvent(
+  message: DebugProtocol.ProtocolMessage,
+): message is DebugProtocol.Event;
+function isEvent<K extends keyof EventMap>(
+  message: DebugProtocol.ProtocolMessage,
+  event: K,
+): message is EventMap[K];
+function isEvent(
+  message: DebugProtocol.ProtocolMessage,
+  event?: string,
+): boolean {
+  return (
+    message.type === "event" &&
+    (!event || (message as DebugProtocol.Event).event === event)
+  );
+}
+
+export class DebugSessionTracker
+  implements vscode.DebugAdapterTrackerFactory, vscode.Disposable
+{
+  private modules = new Map<vscode.DebugSession, DebugProtocol.Module[]>();
+  private modulesChanged = new vscode.EventEmitter<void>();
+  onDidChangeModules: vscode.Event<void> = this.modulesChanged.event;
+
+  dispose() {
+    this.modules.clear();
+    this.modulesChanged.dispose();
+  }
+
+  createDebugAdapterTracker(
+    session: vscode.DebugSession,
+  ): vscode.ProviderResult<vscode.DebugAdapterTracker> {
+    return {
+      onDidSendMessage: (message) => this.onDidSendMessage(session, message),
+      onExit: () => this.onExit(session),
+    };
+  }
+
+  debugSessionModules(session: vscode.DebugSession): DebugProtocol.Module[] {
+    return this.modules.get(session) ?? [];
+  }
+
+  private onExit(session: vscode.DebugSession) {
+    this.modules.delete(session);
+  }
+
+  private onDidSendMessage(
+    session: vscode.DebugSession,
+    message: DebugProtocol.ProtocolMessage,
+  ) {
+    if (isEvent(message, "module")) {
+      const { module, reason } = message.body;
+      const modules = this.modules.get(session) ?? [];
+      switch (reason) {
+        case "new":
+        case "changed": {
+          const index = modules.findIndex((m) => m.id === module.id);
+          if (index !== -1) {
+            modules[index] = module;
+          } else {
+            modules.push(module);
+          }
+          break;
+        }
+        case "removed": {
+          const index = modules.findIndex((m) => m.id === module.id);
+          if (index !== -1) {
+            modules.splice(index, 1);
+          }
+          break;
+        }
+        default:
+          console.error("unexpected module event reason");
+          break;
+      }
+      this.modules.set(session, modules);
+      this.modulesChanged.fire();
+    }
+  }
+}

lldb/tools/lldb-dap/src-ts/debug-session-tracker.ts

@@ -21,7 +21,7 @@ export class DisposableContext implements vscode.Disposable {
    *
    * @param disposable The disposable to register.
    */
-  public pushSubscription(disposable: vscode.Disposable) {
-    this._disposables.push(disposable);
+  public pushSubscription(...disposable: vscode.Disposable[]) {
+    this._disposables.push(...disposable);
   }
 }

lldb/tools/lldb-dap/src-ts/disposable-context.ts

@@ -5,6 +5,8 @@ import { DisposableContext } from "./disposable-context";
 import { LaunchUriHandler } from "./uri-launch-handler";
 import { LLDBDapConfigurationProvider } from "./debug-configuration-provider";
 import { LLDBDapServer } from "./lldb-dap-server";
+import { DebugSessionTracker } from "./debug-session-tracker";
+import { ModuleDataProvider } from "./ui/modules-data-provider";
 
 /**
  * This class represents the extension and manages its life cycle. Other extensions
@@ -31,6 +33,22 @@ export class LLDBDapExtension extends DisposableContext {
       ),
     );
 
+    const sessionTracker = new DebugSessionTracker();
+
+    this.pushSubscription(
+      vscode.debug.registerDebugAdapterTrackerFactory(
+        "lldb-dap",
+        sessionTracker,
+      ),
+    );
+
+    this.pushSubscription(
+      vscode.window.registerTreeDataProvider(
+        "lldb-dap.modulesExplorer",
+        new ModuleDataProvider(sessionTracker),
+      ),
+    );
+
     this.pushSubscription(
       vscode.window.registerUriHandler(new LaunchUriHandler()),
     );

lldb/tools/lldb-dap/src-ts/extension.ts

@@ -0,0 +1,58 @@
+import * as vscode from "vscode";
+import { DebugProtocol } from "@vscode/debugprotocol";
+import { DebugSessionTracker } from "../debug-session-tracker";
+
+export class ModuleDataProvider
+  implements vscode.TreeDataProvider<DebugProtocol.Module>
+{
+  private changeTreeData = new vscode.EventEmitter<void>();
+  readonly onDidChangeTreeData = this.changeTreeData.event;
+
+  constructor(private readonly tracker: DebugSessionTracker) {
+    tracker.onDidChangeModules(() => this.changeTreeData.fire());
+    vscode.debug.onDidChangeActiveDebugSession(() =>
+      this.changeTreeData.fire(),
+    );
+  }
+
+  getTreeItem(module: DebugProtocol.Module): vscode.TreeItem {
+    let treeItem = new vscode.TreeItem(/*label=*/ module.name);
+    if (module.path) {
+      treeItem.description = `${module.id} -- ${module.path}`;
+    } else {
+      treeItem.description = `${module.id}`;
+    }
+
+    const tooltip = new vscode.MarkdownString();
+    tooltip.appendMarkdown(`# Module '${module.name}'\n\n`);
+    tooltip.appendMarkdown(`- **id** : ${module.id}\n`);
+    if (module.addressRange) {
+      tooltip.appendMarkdown(`- **load address** : ${module.addressRange}\n`);
+    }
+    if (module.path) {
+      tooltip.appendMarkdown(`- **path** : ${module.path}\n`);
+    }
+    if (module.version) {
+      tooltip.appendMarkdown(`- **version** : ${module.version}\n`);
+    }
+    if (module.symbolStatus) {
+      tooltip.appendMarkdown(`- **symbol status** : ${module.symbolStatus}\n`);
+    }
+    if (module.symbolFilePath) {
+      tooltip.appendMarkdown(
+        `- **symbol file path** : ${module.symbolFilePath}\n`,
+      );
+    }
+
+    treeItem.tooltip = tooltip;
+    return treeItem;
+  }
+
+  getChildren(): DebugProtocol.Module[] {
+    if (!vscode.debug.activeDebugSession) {
+      return [];
+    }
+
+    return this.tracker.debugSessionModules(vscode.debug.activeDebugSession);
+  }
+}