Rename and document vscode env management declarations

Author: eliericha

integration/vscode/ada/src/ExtensionState.ts

@@ -4,7 +4,7 @@ import { createClient } from './clients';
 import { GnatTaskProvider } from './gnatTaskProvider';
 import { GprTaskProvider } from './gprTaskProvider';
 import { registerTaskProviders } from './taskProviders';
-import { getCustomEnvSettingName } from './helpers';
+import { TERMINAL_ENV_SETTING_NAME } from './helpers';
 
 /**
  * This class encapsulates all state that should be maintained throughout the
@@ -106,9 +106,7 @@ export class ExtensionState {
         //  React to changes made in the environment variables, showing
         //  a popup to reload the VS Code window and thus restart the
         //  Ada extension.
-        const env_config_name = getCustomEnvSettingName();
-
-        if (e.affectsConfiguration(env_config_name)) {
+        if (e.affectsConfiguration(TERMINAL_ENV_SETTING_NAME)) {
             void this.showReloadWindowPopup();
         }
     };

integration/vscode/ada/src/clients.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'fs';
 import * as vscode from 'vscode';
 import { LanguageClient, LanguageClientOptions, ServerOptions } from 'vscode-languageclient/node';
 import { logger } from './extension';
-import { logErrorAndThrow, setCustomEnvironment } from './helpers';
+import { logErrorAndThrow, setTerminalEnvironment } from './helpers';
 
 export function createClient(
     context: vscode.ExtensionContext,
@@ -63,7 +63,7 @@ export function createClient(
     // Copy this process's environment
     const serverEnv: NodeJS.ProcessEnv = { ...process.env };
     // Set custom environment
-    setCustomEnvironment(serverEnv);
+    setTerminalEnvironment(serverEnv);
 
     logger.debug(`Environment for ${name}:`);
     for (const key in serverEnv) {

integration/vscode/ada/src/debugConfigProvider.ts

@@ -1,7 +1,7 @@
 import assert from 'assert';
 import * as vscode from 'vscode';
 import { adaExtState } from './extension';
-import { AdaMain, exe, getAdaMains, getEvaluatedCustomEnv, getProjectFile } from './helpers';
+import { AdaMain, exe, getAdaMains, getEvaluatedTerminalEnv, getProjectFile } from './helpers';
 import { BUILD_PROJECT_TASK_NAME, getBuildTaskName } from './taskProviders';
 import path from 'path';
 import { existsSync } from 'fs';
@@ -97,7 +97,7 @@ function getOrFindGdb(): string | undefined {
         /**
          * If undefined yet, try to compute it.
          */
-        const env = getEvaluatedCustomEnv();
+        const env = getEvaluatedTerminalEnv();
         let pathVal: string;
         if (env && 'PATH' in env) {
             pathVal = env.PATH;

integration/vscode/ada/src/extension.ts

@@ -30,8 +30,8 @@ import { initializeDebugging } from './debugConfigProvider';
 import { initializeTestView } from './gnattest';
 import {
     assertSupportedEnvironments,
-    getCustomEnvSettingName,
-    getEvaluatedCustomEnv,
+    TERMINAL_ENV_SETTING_NAME,
+    getEvaluatedTerminalEnv,
     startedInDebugMode,
 } from './helpers';
 
@@ -127,15 +127,15 @@ async function activateExtension(context: vscode.ExtensionContext) {
     assertSupportedEnvironments(logger);
 
     // Log the environment that the extension (and all VS Code) will be using
-    const customEnv = getEvaluatedCustomEnv();
+    const customEnv = getEvaluatedTerminalEnv();
     if (customEnv && Object.keys(customEnv).length > 0) {
-        logger.info(`Custom environment variables from ${getCustomEnvSettingName()}`);
+        logger.info(`Custom environment variables from ${TERMINAL_ENV_SETTING_NAME}`);
         for (const varName in customEnv) {
             const varValue: string = customEnv[varName];
             logger.info(`${varName}=${varValue}`);
         }
     } else {
-        logger.debug('No custom environment variables set in %s', getCustomEnvSettingName());
+        logger.debug('No custom environment variables set in %s', TERMINAL_ENV_SETTING_NAME);
     }
 
     // Create the Ada and GPR clients.

integration/vscode/ada/src/helpers.ts

@@ -109,39 +109,33 @@ export function substituteVariables(str: string, recursive = false): string {
     return str;
 }
 
-/*
-    Environment setting helper functions
-*/
-
-export function getCustomEnv() {
-    const env_config_name = getCustomEnvSettingName();
+/**
+ * Name of the `terminal.integrated.env.*` setting applicable to the current platform.
+ */
+export const TERMINAL_ENV_SETTING_NAME =
+    'terminal.integrated.env.' +
+    (platform() == 'darwin' ? 'osx' : platform() == 'win32' ? 'windows' : 'linux');
 
+/**
+ *
+ * @returns the value of the applicable `terminal.integrated.env.*` setting,
+ * without evaluation of macros such as `${env:...}`.
+ */
+export function getTerminalEnv() {
     const custom_env = vscode.workspace
         .getConfiguration()
-        .get<{ [name: string]: string }>(env_config_name);
+        .get<{ [name: string]: string }>(TERMINAL_ENV_SETTING_NAME);
 
     return custom_env;
 }
 
-export function getCustomEnvSettingName() {
-    const user_platform = platform();
-    let env_config_name = 'terminal.integrated.env';
-
-    switch (user_platform) {
-        case 'darwin':
-            env_config_name += '.osx';
-            break;
-        case 'win32':
-            env_config_name += '.windows';
-            break;
-        default:
-            env_config_name += '.linux';
-    }
-    return env_config_name;
-}
-
-export function getEvaluatedCustomEnv() {
-    const custom_env = getCustomEnv();
+/**
+ *
+ * @returns the value of the applicable `terminal.integrated.env.*` setting,
+ * after evaluation of macros such as `${env:...}`.
+ */
+export function getEvaluatedTerminalEnv() {
+    const custom_env = getTerminalEnv();
 
     if (custom_env) {
         for (const var_name in custom_env) {
@@ -160,17 +154,13 @@ export function getEvaluatedCustomEnv() {
  * Read the environment variables specified in the vscode setting
  * `terminal.integrated.env.<os>` and set them in the given ProcessEnv object.
  *
- * If no targetEnv is given, `process.env` is used as a target environment.
+ * The targetEnv can be `process.env` to apply the changes to the environment of
+ * the running process.
  */
-export function setCustomEnvironment(targetEnv?: NodeJS.ProcessEnv) {
-    if (!targetEnv) {
-        targetEnv = process.env;
-    }
-
+export function setTerminalEnvironment(targetEnv: NodeJS.ProcessEnv) {
     // Retrieve the user's custom environment variables if specified in their
-    // settings/workspace: we'll then launch any child process with this custom
-    // environment
-    const custom_env = getEvaluatedCustomEnv();
+    // settings/workspace
+    const custom_env = getEvaluatedTerminalEnv();
 
     if (custom_env) {
         for (const var_name in custom_env) {
@@ -183,7 +173,7 @@ export function setCustomEnvironment(targetEnv?: NodeJS.ProcessEnv) {
 export function assertSupportedEnvironments(mainChannel: winston.Logger) {
     // Get the ALS environment variable from the custom environment, or from the
     // process environment
-    const customEnv = getEvaluatedCustomEnv();
+    const customEnv = getEvaluatedTerminalEnv();
     const als = customEnv?.ALS ?? process.env.ALS;
     if (als) {
         // The User provided an external ALS executable. Do not perform any