[Lldb-commits] [lldb] 20b8664 - [vscode-lldb] Support lldb-dap environment in debug configuration (#153536)
via lldb-commits
lldb-commits at lists.llvm.org
Thu Aug 28 14:21:32 PDT 2025
Author: Roy Shi
Date: 2025-08-28T14:21:28-07:00
New Revision: 20b86644e45a76c4fa33c4a05c05b0726607cf77
URL: https://github.com/llvm/llvm-project/commit/20b86644e45a76c4fa33c4a05c05b0726607cf77
DIFF: https://github.com/llvm/llvm-project/commit/20b86644e45a76c4fa33c4a05c05b0726607cf77.diff
LOG: [vscode-lldb] Support lldb-dap environment in debug configuration (#153536)
# Changes
1. Add a new debug configuration field called `debugAdapterEnv`. It accepts a string-valued dictionary or array.
1. This input format is consistent with the (program's) `env` debug configuration.
2. In the adapter descriptor factory, honor the said field before looking at the VS Code settings `Lldb-dap: Environment `.
1. This order is consistent with how things are done for other debug configuration fields, e.g. lldb-dap path and args.
3. In the lldb-dap server, note down the environment entries as a part of the adapter spawn info (now it becomes "path + args + env"), and prompt the user to restart server if such info has changed.
# Motivation
1. Adapter environment can be set in `launch.json`.
2. Other debugger extensions can invoke the lldb-dap extension with adapter environment (via debug configuration).
# Tests
See PR #153536.
Added:
Modified:
lldb/tools/lldb-dap/package.json
lldb/tools/lldb-dap/src-ts/debug-adapter-factory.ts
lldb/tools/lldb-dap/src-ts/lldb-dap-server.ts
Removed:
################################################################################
diff --git a/lldb/tools/lldb-dap/package.json b/lldb/tools/lldb-dap/package.json
index f11b64aa72ae4..8c6c1b4ae6ebb 100644
--- a/lldb/tools/lldb-dap/package.json
+++ b/lldb/tools/lldb-dap/package.json
@@ -398,6 +398,29 @@
},
"markdownDescription": "The list of additional arguments used to launch the debug adapter executable. Overrides any user or workspace settings."
},
+ "debugAdapterEnv": {
+ "anyOf": [
+ {
+ "type": "object",
+ "markdownDescription": "Additional environment variables to set when launching the debug adapter executable. E.g. `{ \"FOO\": \"1\" }`",
+ "patternProperties": {
+ ".*": {
+ "type": "string"
+ }
+ },
+ "default": {}
+ },
+ {
+ "type": "array",
+ "markdownDescription": "Additional environment variables to set when launching the debug adapter executable. E.g. `[\"FOO=1\", \"BAR\"]`",
+ "items": {
+ "type": "string",
+ "pattern": "^((\\w+=.*)|^\\w+)$"
+ },
+ "default": []
+ }
+ ]
+ },
"program": {
"type": "string",
"description": "Path to the program to debug."
diff --git a/lldb/tools/lldb-dap/src-ts/debug-adapter-factory.ts b/lldb/tools/lldb-dap/src-ts/debug-adapter-factory.ts
index 157aa2ac76a1f..f7e92ee95ca32 100644
--- a/lldb/tools/lldb-dap/src-ts/debug-adapter-factory.ts
+++ b/lldb/tools/lldb-dap/src-ts/debug-adapter-factory.ts
@@ -68,6 +68,40 @@ async function findDAPExecutable(): Promise<string | undefined> {
return undefined;
}
+/**
+ * Validates the DAP environment provided in the debug configuration.
+ * It must be a dictionary of string keys and values OR an array of string values.
+ *
+ * @param debugConfigEnv The supposed DAP environment that will be validated
+ * @returns Whether or not the DAP environment is valid
+ */
+function validateDAPEnv(debugConfigEnv: any): boolean {
+ // If the env is an object, it should have string values.
+ // The keys are guaranteed to be strings.
+ if (
+ typeof debugConfigEnv === "object" &&
+ Object.values(debugConfigEnv).findIndex(
+ (entry) => typeof entry !== "string",
+ ) !== -1
+ ) {
+ return false;
+ }
+
+ // If the env is an array, it should have string values which match the regex.
+ if (
+ Array.isArray(debugConfigEnv) &&
+ debugConfigEnv.findIndex(
+ (entry) =>
+ typeof entry !== "string" || !/^((\\w+=.*)|^\\w+)$/.test(entry),
+ ) !== -1
+ ) {
+ return false;
+ }
+
+ // The env is valid.
+ return true;
+}
+
/**
* Retrieves the lldb-dap executable path either from settings or the provided
* {@link vscode.DebugConfiguration}.
@@ -157,6 +191,51 @@ async function getDAPArguments(
.get<string[]>("arguments", []);
}
+/**
+ * Retrieves the environment that will be provided to lldb-dap either from settings or the provided
+ * {@link vscode.DebugConfiguration}.
+ *
+ * @param workspaceFolder The {@link vscode.WorkspaceFolder} that the debug session will be launched within
+ * @param configuration The {@link vscode.DebugConfiguration} that will be launched
+ * @throws An {@link ErrorWithNotification} if something went wrong
+ * @returns The environment that will be provided to lldb-dap
+ */
+async function getDAPEnvironment(
+ workspaceFolder: vscode.WorkspaceFolder | undefined,
+ configuration: vscode.DebugConfiguration,
+): Promise<{ [key: string]: string }> {
+ const debugConfigEnv = configuration.debugAdapterEnv;
+ if (debugConfigEnv) {
+ if (validateDAPEnv(debugConfigEnv) === false) {
+ throw new ErrorWithNotification(
+ "The debugAdapterEnv property must be a dictionary of string keys and values OR an array of string values. Please update your launch configuration",
+ new ConfigureButton(),
+ );
+ }
+
+ // Transform, so that the returned value is always a dictionary.
+ if (Array.isArray(debugConfigEnv)) {
+ const ret: { [key: string]: string } = {};
+ for (const envVar of debugConfigEnv as string[]) {
+ const equalSignPos = envVar.search("=");
+ if (equalSignPos >= 0) {
+ ret[envVar.substr(0, equalSignPos)] = envVar.substr(equalSignPos + 1);
+ } else {
+ ret[envVar] = "";
+ }
+ }
+ return ret;
+ } else {
+ return debugConfigEnv;
+ }
+ }
+
+ const config = vscode.workspace.workspaceFile
+ ? vscode.workspace.getConfiguration("lldb-dap")
+ : vscode.workspace.getConfiguration("lldb-dap", workspaceFolder);
+ return config.get<{ [key: string]: string }>("environment") || {};
+}
+
/**
* 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.
@@ -182,12 +261,16 @@ export async function createDebugAdapterExecutable(
if (log_path) {
env["LLDBDAP_LOG"] = log_path;
} else if (
- vscode.workspace.getConfiguration("lldb-dap").get("captureSessionLogs", false)
+ vscode.workspace
+ .getConfiguration("lldb-dap")
+ .get("captureSessionLogs", false)
) {
env["LLDBDAP_LOG"] = logFilePath.get(LogType.DEBUG_SESSION);
}
- const configEnvironment =
- config.get<{ [key: string]: string }>("environment") || {};
+ const configEnvironment = await getDAPEnvironment(
+ workspaceFolder,
+ configuration,
+ );
const dapPath = await getDAPExecutable(workspaceFolder, configuration);
const dbgOptions = {
diff --git a/lldb/tools/lldb-dap/src-ts/lldb-dap-server.ts b/lldb/tools/lldb-dap/src-ts/lldb-dap-server.ts
index 5f9d8efdcb3a3..300b12d1cce1b 100644
--- a/lldb/tools/lldb-dap/src-ts/lldb-dap-server.ts
+++ b/lldb/tools/lldb-dap/src-ts/lldb-dap-server.ts
@@ -11,6 +11,7 @@ import * as vscode from "vscode";
export class LLDBDapServer implements vscode.Disposable {
private serverProcess?: child_process.ChildProcessWithoutNullStreams;
private serverInfo?: Promise<{ host: string; port: number }>;
+ private serverSpawnInfo?: string[];
constructor() {
vscode.commands.registerCommand(
@@ -34,7 +35,7 @@ export class LLDBDapServer implements vscode.Disposable {
options?: child_process.SpawnOptionsWithoutStdio,
): Promise<{ host: string; port: number } | undefined> {
const dapArgs = [...args, "--connection", "listen://localhost:0"];
- if (!(await this.shouldContinueStartup(dapPath, dapArgs))) {
+ if (!(await this.shouldContinueStartup(dapPath, dapArgs, options?.env))) {
return undefined;
}
@@ -70,6 +71,7 @@ export class LLDBDapServer implements vscode.Disposable {
}
});
this.serverProcess = process;
+ this.serverSpawnInfo = this.getSpawnInfo(dapPath, dapArgs, options?.env);
});
return this.serverInfo;
}
@@ -85,12 +87,14 @@ export class LLDBDapServer implements vscode.Disposable {
private async shouldContinueStartup(
dapPath: string,
args: string[],
+ env: NodeJS.ProcessEnv | { [key: string]: string } | undefined,
): Promise<boolean> {
- if (!this.serverProcess || !this.serverInfo) {
+ if (!this.serverProcess || !this.serverInfo || !this.serverSpawnInfo) {
return true;
}
- if (isDeepStrictEqual(this.serverProcess.spawnargs, [dapPath, ...args])) {
+ const newSpawnInfo = this.getSpawnInfo(dapPath, args, env);
+ if (isDeepStrictEqual(this.serverSpawnInfo, newSpawnInfo)) {
return true;
}
@@ -102,11 +106,11 @@ export class LLDBDapServer implements vscode.Disposable {
The previous lldb-dap server was started with:
-${this.serverProcess.spawnargs.join(" ")}
+${this.serverSpawnInfo.join(" ")}
The new lldb-dap server will be started with:
-${dapPath} ${args.join(" ")}
+${newSpawnInfo.join(" ")}
Restarting the server will interrupt any existing debug sessions and start a new server.`,
},
@@ -143,4 +147,18 @@ Restarting the server will interrupt any existing debug sessions and start a new
this.serverInfo = undefined;
}
}
+
+ getSpawnInfo(
+ path: string,
+ args: string[],
+ env: NodeJS.ProcessEnv | { [key: string]: string } | undefined,
+ ): string[] {
+ return [
+ path,
+ ...args,
+ ...Object.entries(env ?? {}).map(
+ (entry) => String(entry[0]) + "=" + String(entry[1]),
+ ),
+ ];
+ }
}
More information about the lldb-commits
mailing list