prompt the user to restart the server if the executable or arguments change

Author: matthewbastien

lldb/tools/lldb-dap/package.json

@@ -163,6 +163,14 @@
               "program"
             ],
             "properties": {
+              "debugAdapterHostname": {
+                "type": "string",
+                "markdownDescription": "The hostname that an existing lldb-dap executable is listening on."
+              },
+              "debugAdapterPort": {
+                "type": "number",
+                "markdownDescription": "The port that an existing lldb-dap executable is listening on."
+              },
               "debugAdapterExecutable": {
                 "type": "string",
                 "markdownDescription": "The absolute path to the LLDB debug adapter executable to use."
@@ -360,6 +368,14 @@
           },
           "attach": {
             "properties": {
+              "debugAdapterHostname": {
+                "type": "string",
+                "markdownDescription": "The hostname that an existing lldb-dap executable is listening on."
+              },
+              "debugAdapterPort": {
+                "type": "number",
+                "markdownDescription": "The port that an existing lldb-dap executable is listening on."
+              },
               "debugAdapterExecutable": {
                 "type": "string",
                 "markdownDescription": "The absolute path to the LLDB debug adapter executable to use."

lldb/tools/lldb-dap/src-ts/debug-adapter-factory.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs/promises";
 
 const exec = util.promisify(child_process.execFile);
 
-export async function isExecutable(path: string): Promise<Boolean> {
+async function isExecutable(path: string): Promise<Boolean> {
   try {
     await fs.access(path, fs.constants.X_OK);
   } catch {
@@ -66,19 +66,17 @@ async function findDAPExecutable(): Promise<string | undefined> {
 }
 
 async function getDAPExecutable(
-  session: vscode.DebugSession,
+  folder: vscode.WorkspaceFolder | undefined,
+  configuration: vscode.DebugConfiguration,
 ): Promise<string | undefined> {
   // Check if the executable was provided in the launch configuration.
-  const launchConfigPath = session.configuration["debugAdapterExecutable"];
+  const launchConfigPath = configuration["debugAdapterExecutable"];
   if (typeof launchConfigPath === "string" && launchConfigPath.length !== 0) {
     return launchConfigPath;
   }
 
   // Check if the executable was provided in the extension's configuration.
-  const config = vscode.workspace.getConfiguration(
-    "lldb-dap",
-    session.workspaceFolder,
-  );
+  const config = vscode.workspace.getConfiguration("lldb-dap", folder);
   const configPath = config.get<string>("executable-path");
   if (configPath && configPath.length !== 0) {
     return configPath;
@@ -93,9 +91,12 @@ async function getDAPExecutable(
   return undefined;
 }
 
-function getDAPArguments(session: vscode.DebugSession): string[] {
+function getDAPArguments(
+  folder: vscode.WorkspaceFolder | undefined,
+  configuration: vscode.DebugConfiguration,
+): string[] {
   // Check the debug configuration for arguments first
-  const debugConfigArgs = session.configuration.debugAdapterArgs;
+  const debugConfigArgs = configuration.debugAdapterArgs;
   if (
     Array.isArray(debugConfigArgs) &&
     debugConfigArgs.findIndex((entry) => typeof entry !== "string") === -1
@@ -104,129 +105,110 @@ function getDAPArguments(session: vscode.DebugSession): string[] {
   }
   // Fall back on the workspace configuration
   return vscode.workspace
-    .getConfiguration("lldb-dap")
+    .getConfiguration("lldb-dap", folder)
     .get<string[]>("arguments", []);
 }
 
-async function isServerModeSupported(exe: string): Promise<boolean> {
-  const { stdout } = await exec(exe, ["--help"]);
-  return /--connection/.test(stdout);
+/**
+ * Shows a modal when the debug adapter's path is not found
+ */
+async function showLLDBDapNotFoundMessage(path?: string) {
+  const message =
+    path !== undefined
+      ? `Debug adapter path: ${path} is not a valid file`
+      : "Unable to find the path to the LLDB debug adapter executable.";
+  const openSettingsAction = "Open Settings";
+  const callbackValue = await vscode.window.showErrorMessage(
+    message,
+    { modal: true },
+    openSettingsAction,
+  );
+
+  if (openSettingsAction === callbackValue) {
+    vscode.commands.executeCommand(
+      "workbench.action.openSettings",
+      "lldb-dap.executable-path",
+    );
+  }
 }
 
 /**
- * This class defines a factory used to find the lldb-dap binary to use
- * depending on the session configuration.
+ * Creates a new {@link vscode.DebugAdapterExecutable} based on the provided workspace folder and
+ * debug configuration. Assumes that the given debug configuration is for a local launch of lldb-dap.
+ *
+ * @param folder The {@link vscode.WorkspaceFolder} that the debug session will be launched within
+ * @param configuration The {@link vscode.DebugConfiguration}
+ * @param userInteractive Whether or not this was called due to user interaction (determines if modals should be shown)
+ * @returns
  */
-export class LLDBDapDescriptorFactory
-  implements vscode.DebugAdapterDescriptorFactory, vscode.Disposable
-{
-  private server?: Promise<{
-    process: child_process.ChildProcess;
-    host: string;
-    port: number;
-  }>;
-
-  dispose() {
-    this.server?.then(({ process }) => {
-      process.kill();
-    });
+export async function createDebugAdapterExecutable(
+  folder: vscode.WorkspaceFolder | undefined,
+  configuration: vscode.DebugConfiguration,
+  userInteractive?: boolean,
+): Promise<vscode.DebugAdapterExecutable | undefined> {
+  const config = vscode.workspace.getConfiguration("lldb-dap", folder);
+  const log_path = config.get<string>("log-path");
+  let env: { [key: string]: string } = {};
+  if (log_path) {
+    env["LLDBDAP_LOG"] = log_path;
   }
+  const configEnvironment =
+    config.get<{ [key: string]: string }>("environment") || {};
+  const dapPath = await getDAPExecutable(folder, configuration);
 
-  async createDebugAdapterDescriptor(
-    session: vscode.DebugSession,
-    _executable: vscode.DebugAdapterExecutable | undefined,
-  ): Promise<vscode.DebugAdapterDescriptor | undefined> {
-    const config = vscode.workspace.getConfiguration(
-      "lldb-dap",
-      session.workspaceFolder,
-    );
-
-    const log_path = config.get<string>("log-path");
-    let env: { [key: string]: string } = {};
-    if (log_path) {
-      env["LLDBDAP_LOG"] = log_path;
+  if (!dapPath) {
+    if (userInteractive) {
+      showLLDBDapNotFoundMessage();
     }
-    const configEnvironment =
-      config.get<{ [key: string]: string }>("environment") || {};
-    const dapPath = await getDAPExecutable(session);
+    return undefined;
+  }
 
-    if (!dapPath) {
-      LLDBDapDescriptorFactory.showLLDBDapNotFoundMessage();
-      return undefined;
+  if (!(await isExecutable(dapPath))) {
+    if (userInteractive) {
+      showLLDBDapNotFoundMessage(dapPath);
     }
+    return undefined;
+  }
 
-    if (!(await isExecutable(dapPath))) {
-      LLDBDapDescriptorFactory.showLLDBDapNotFoundMessage(dapPath);
-      return;
-    }
+  const dbgOptions = {
+    env: {
+      ...configEnvironment,
+      ...env,
+    },
+  };
+  const dbgArgs = getDAPArguments(folder, configuration);
+
+  return new vscode.DebugAdapterExecutable(dapPath, dbgArgs, dbgOptions);
+}
 
-    const dbgOptions = {
-      env: {
-        ...configEnvironment,
-        ...env,
-      },
-    };
-    const dbgArgs = getDAPArguments(session);
-
-    const serverMode = config.get<boolean>("serverMode", false);
-    if (serverMode && (await isServerModeSupported(dapPath))) {
-      const { host, port } = await this.startServer(
-        dapPath,
-        dbgArgs,
-        dbgOptions,
+/**
+ * This class defines a factory used to find the lldb-dap binary to use
+ * depending on the session configuration.
+ */
+export class LLDBDapDescriptorFactory
+  implements vscode.DebugAdapterDescriptorFactory
+{
+  async createDebugAdapterDescriptor(
+    session: vscode.DebugSession,
+    executable: vscode.DebugAdapterExecutable | undefined,
+  ): Promise<vscode.DebugAdapterDescriptor | undefined> {
+    if (executable) {
+      throw new Error(
+        "Setting the debug adapter executable in the package.json is not supported.",
       );
-      return new vscode.DebugAdapterServer(port, host);
     }
 
-    return new vscode.DebugAdapterExecutable(dapPath, dbgArgs, dbgOptions);
-  }
-
-  startServer(
-    dapPath: string,
-    args: string[],
-    options: child_process.CommonSpawnOptions,
-  ): Promise<{ host: string; port: number }> {
-    if (this.server) {
-      return this.server;
+    // Use a server connection if the debugAdapterPort is provided
+    if (session.configuration.debugAdapterPort) {
+      return new vscode.DebugAdapterServer(
+        session.configuration.debugAdapterPort,
+        session.configuration.debugAdapterHost,
+      );
     }
 
-    this.server = new Promise((resolve) => {
-      args.push("--connection", "connect://localhost:0");
-      const server = child_process.spawn(dapPath, args, options);
-      server.stdout!.setEncoding("utf8").once("data", (data: string) => {
-        const connection = /connection:\/\/\[([^\]]+)\]:(\d+)/.exec(data);
-        if (connection) {
-          const host = connection[1];
-          const port = Number(connection[2]);
-          resolve({ process: server, host, port });
-        }
-      });
-      server.on("exit", () => {
-        this.server = undefined;
-      });
-    });
-    return this.server;
-  }
-
-  /**
-   * Shows a message box when the debug adapter's path is not found
-   */
-  static async showLLDBDapNotFoundMessage(path?: string | undefined) {
-    const message =
-      path !== undefined
-        ? `Debug adapter path: ${path} is not a valid file`
-        : "Unable to find the path to the LLDB debug adapter executable.";
-    const openSettingsAction = "Open Settings";
-    const callbackValue = await vscode.window.showErrorMessage(
-      message,
-      openSettingsAction,
+    return createDebugAdapterExecutable(
+      session.workspaceFolder,
+      session.configuration,
     );
-
-    if (openSettingsAction === callbackValue) {
-      vscode.commands.executeCommand(
-        "workbench.action.openSettings",
-        "lldb-dap.executable-path",
-      );
-    }
   }
 }

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

@@ -0,0 +1,106 @@
+import * as vscode from "vscode";
+import * as child_process from "child_process";
+import * as util from "util";
+import { LLDBDapServer } from "./lldb-dap-server";
+import { createDebugAdapterExecutable } from "./debug-adapter-factory";
+
+const exec = util.promisify(child_process.execFile);
+
+/**
+ * Shows an error message to the user that optionally allows them to open their
+ * launch.json to configure it.
+ *
+ * @param message The error message to display to the user
+ * @returns `undefined` if the debug session should stop or `null` if the launch.json should be opened
+ */
+async function showErrorWithConfigureButton(
+  message: string,
+): Promise<null | undefined> {
+  const userSelection = await vscode.window.showErrorMessage(
+    message,
+    { modal: true },
+    "Configure",
+  );
+
+  if (userSelection === "Configure") {
+    return null; // Stops the debug session and opens the launch.json for editing
+  }
+
+  return undefined; // Only stops the debug session
+}
+
+/**
+ * Determines whether or not the given lldb-dap executable supports executing
+ * in server mode.
+ *
+ * @param exe the path to the lldb-dap executable
+ * @returns a boolean indicating whether or not lldb-dap supports server mode
+ */
+async function isServerModeSupported(exe: string): Promise<boolean> {
+  const { stdout } = await exec(exe, ["--help"]);
+  return /--connection/.test(stdout);
+}
+
+export class LLDBDapConfigurationProvider
+  implements vscode.DebugConfigurationProvider
+{
+  constructor(private readonly server: LLDBDapServer) {}
+
+  async resolveDebugConfiguration(
+    folder: vscode.WorkspaceFolder | undefined,
+    debugConfiguration: vscode.DebugConfiguration,
+    _token?: vscode.CancellationToken,
+  ): Promise<vscode.DebugConfiguration | null | undefined> {
+    if (
+      "debugAdapterHost" in debugConfiguration &&
+      !("debugAdapterPort" in debugConfiguration)
+    ) {
+      return showErrorWithConfigureButton(
+        "A debugAdapterPort must be provided when debugAdapterHost is set. Please update your launch configuration.",
+      );
+    }
+
+    if (
+      "debugAdapterPort" in debugConfiguration &&
+      ("debugAdapterExecutable" in debugConfiguration ||
+        "debugAdapterArgs" in debugConfiguration)
+    ) {
+      return showErrorWithConfigureButton(
+        "The debugAdapterPort property is incompatible with debugAdapterExecutable and debugAdapterArgs. Please update your launch configuration.",
+      );
+    }
+
+    // Server mode needs to be handled here since DebugAdapterDescriptorFactory
+    // will show an unhelpful error if it returns undefined. We'd rather show a
+    // nicer error message here and allow stopping the debug session gracefully.
+    const config = vscode.workspace.getConfiguration("lldb-dap", folder);
+    if (config.get<boolean>("serverMode", false)) {
+      const executable = await createDebugAdapterExecutable(
+        folder,
+        debugConfiguration,
+        /* userInteractive */ true,
+      );
+      if (!executable) {
+        return undefined;
+      }
+      if (await isServerModeSupported(executable.command)) {
+        const serverInfo = await this.server.start(
+          executable.command,
+          executable.args,
+          executable.options,
+        );
+        if (!serverInfo) {
+          return undefined;
+        }
+        // Use a debug adapter host and port combination rather than an executable
+        // and list of arguments.
+        delete debugConfiguration.debugAdapterExecutable;
+        delete debugConfiguration.debugAdapterArgs;
+        debugConfiguration.debugAdapterHost = serverInfo.host;
+        debugConfiguration.debugAdapterPort = serverInfo.port;
+      }
+    }
+
+    return debugConfiguration;
+  }
+}