Allow extensions to modify terminal environment variables

[DanTup]

Users sometimes want to set SDK paths local to their project to pin the versions of them (or to progressively move projects to the next version). There are two places where they'd want these paths to apply:

1. The extension uses it to load the correct SDK (eg. for language services, debugger, etc.)
2. In the integrated terminal

Currently it doesn't seem like there's a way to provide a path once to be used for both of these purposes so the user has to set the path in two places (one in extensions settings and the other in terminal path) and keep them in sync.

I thought maybe I could read the terminals path and use that when locating my SDK, but I tried this:

{
  "terminal.integrated.env.windows": {
    "PATH": "${env:PATH};C:\bin"
  }
}

However if I read that value from "terminal.integrated.env.windows" I get the literal string above without the ${env:PATH} being resolved. Although I could resolve that myself as a special case, maybe there's a better way to handle this (like allowing the user to specify paths that will be prepended to the terminal paths that extensions could use too).

[Tyriar]

@sandy081 is there a way to read settings in the API and then resolve the variables inside them?

[sandy081]

@Tyriar Following is the API to read configurations

vscode.workspace.getConfiguation()

But I do not think there is an API to resolve variables.

@isidorn might have an idea?

[isidorn]

@DanTup @sandy081 there is no extension API to resolve variables
We do not support variables resolving in settings inside vscode (there is a seperate feature request). Dut to the above it is not possible to read settings in the API and resolve variables

[DanTup]

My request here is not specifically about resolving variables, but rather about providing some solution to this problem. I don't think reading from the terminal path as suggested above is the best one. However, I do think it'd be good to provide some way for a user to be able to specify folder-level paths that would apply to in-built terminals and be readable by extensions to allow projects to be pinned to specific versions of SDKs/cli tools.

[sandy081]

@DanTup

Re: SDKs, If I understand correctly, you are asking for the support for the user able to provide paths to SDKs relative to the current workspace in settings? For example like

"java.sdk": "${workspace}/lib/java/sdk

And when the extension gets the resolved value when the above setting is read?

I am not sure if I understand the relation between in-built terminals and specific versions of SDKs. Can you please elaborate more ?

[DanTup]

@sandy081 It doesn't need to be relative, I just want the user to be able to configure a path at a workspace-level that will be used for two things:

1. By my extension to look find the SDK
2. By Code to prepend to the PATH variable for integrated terminals

I already have a setting for 1 (dart.sdkPath/dart.flutterSdkPath) however because Code doesn't use them, if the user types dart or flutter in the integrated terminal then they'll get the version from their normal PATH and not the version they've pinned this project to.

Obviously it doesn't make sense for Code to read my specific settings, so I'm hoping Code can support a general setting for users to configure PATHs for the integrated terminal that is also reasonable for extensions to read for their own searching.

Maybe if the user could prepend paths so that there are no variables required or something?

{
  "terminal.integrated.env.windows": {
    "PATH": {
      "prepend": "C:\bin",
    }
  }
}

I'd also like to be able to set it, so that if the user picks an SDK from a picker, I can write it somewhere that will apply to newly created terminals.

[DanTup]

Maybe it shouldn't be inside terminal.integrated but a more general workspace setting for "additional paths" that can be pre-pended by terminals and also consumed by extensions.

[sandy081]

@Tyriar After going through above comments, it looks like this request is to support PATH in the integrated terminal.

[DanTup]

To be clear, the request is for a workspace-level PATH which is also readable by extensions.

[Tyriar]

Is #45692 a solution to the same problem? You can then have some path as a setting:

"go.gopath": "C:\\some\\path"

And then resolve a command inside the .env. setting?

 "terminal.integrated.env.windows": {
    "PATH": "${env:PATH};${command:go.gopath}"
  }

Or a setting?

 "terminal.integrated.env.windows": {
    "PATH": "${env:PATH};${setting:go.gopath}"
  }

[DanTup]

@Tyriar Almost! That would still require the user to do two things:

1. Set the SDK via the extension
2. Configure their path to call the command

Doing this in every project is tedious. Most likely the user will start a new project, change their SDK, then discover the terminal is wrong and be frustrated they have to go copy/paste this chunk again.

Really I'd like something that an extension can write that would automatically be pre-fixed into the paths. Eg., in Dart Code you can click on the SDK version in the status bar and quickly change it:

https://dartcode.org/docs/quickly-switching-between-sdk-versions/

I guess it's very similar to the TypeScript version picker. We'd like this to seamlessly fix paths for the terminal (for new ones, at least, we don't expect existing terminals to be affected). While we could probably write to that setting above, I think it may require a restart, and it'd be nice if we could do this invisibly (not have an additional change show up in addition to the SDK path we've already written for the extension to use).

Ideally, I'd want it to just be as simple as something like this in my workspace settings:

{
  "env.additionalPaths": [
    // ...
  ]
}

These would be prefixed into terminals paths and extensions are free to read/write them. The setting isn't specific to the extension or the terminal, it's a generic way for the user to tell anyone that cares that they have some preferred paths for this workspace that should be searched before PATH. We'd use them first for looking for SDKs and if the user uses our sdk-picker we will insert into the top of that array (and remove anything we know is an older SDK).

[Tyriar]

While we could probably write to that setting above, I think it may require a restart, and it'd be nice if we could do this invisibly

You are correct that you won't be able to touch existing terminals, but you shouldn't need a restart. What I was thinking was you could check if the setting has been set and give a notification if that's the case, otherwise just set it.

These would be prefixed into terminals paths and extensions are free to read/write them.

I'm hesitant to promote PATH to something more than just another environment variable that it is now.

---

@ramya-rao-a @DonJayamanne any opinions on this? Seems relevant to most language extensions.

[Tyriar]

Update

I'm just in the process of adding the setting which should be in soon, the UI changes are merged in and will be in Monday's build. These screenshots were taken with the help of the new terminal-sample which calls this API microsoft/vscode-extension-samples@81d47e0

When there are changes that need to be made:

New rich hover, the first one outside the editor. It includes an action to relaunch the terminal, this is a new command generally available which will kill the terminal process, clear the terminal and create a new process using the same launch configuration (but extension env changes will be refreshed):

Example of splits and text under the indicator:

Info hover, also shows the hover gets anchored on the bottom if it doesn't have room available above:

Here it is in action:

[Tyriar]

Update:

We're going to move the API from window to ExtensionContext and make persistent a property (default: true) on EnvironmentVariableCollection:

export interface ExtensionContext {
	/**
	 * Creates or returns the extension's environment variable collection for this workspace,
	 * enabling changes to be applied to terminal environment variables.
	 */
	readonly environmentVariableCollection: EnvironmentVariableCollection;
}


export interface EnvironmentVariableCollection {
	/**
	 * Whether the collection should be cached for the workspace and applied to the terminal across
	 * window reloads. When true the collection will be active immediately such when the window
	 * reloads. Additionally, this API will return the cached version if it exists. The collection
	 * will be invalidated when the extension is uninstalled or when the collection is disposed.
	 * Defaults to true.
	 */
	persistent: boolean;
}

I guess this would mean also getting rid of EnvironmentVariableCollection.dispose in favor of just using EnvironmentVariableCollection.clear.

Current unknown is whether it should be named workspaceEnvironmentVariableCollection, if we want to eventually do a globalEnvironmentVariableCollection.

[connor4312]

Small thing: it would be nice to be able to accept the environment variable changes by clicking on the ⚠️ icon. I've tried to do that a few times automatically before remembering I need to go to the link inside the tooltip.

[Tyriar]

@connor4312 accept as in relaunch the terminal? It's could lose work though

[Tyriar]

Also right now click events go through to the terminal, so mouse events still work there even if the info/warning icon is visible.

[connor4312]

accept as in relaunch the terminal? It's could lose work though

Yea. It is dangerous but it's not an area I click very often, so I would feel safe that I wouldn't accidentally click it. The ⚠️ state is also not one that users should want to stay in for very long.

---

When implementing auto-attach using this API I ran into some awkwardness from the fact that the debug-auto-launch extension couldn't read the environment variables that js-debug had exposed. Some more details here, it would be nice (for me 😛 ) if we could expose some kind of reflection API: #95807

[Tyriar]

Just had a discussion about this, it will probably eventually move into the the terminal tab #10546 near the x

[Tyriar]

@connor4312 can js-debug depend on debug-auto-launch and the environment contribution is done by debug-auto-launch?

[connor4312]

The difficulty there is that the environment variables must be unset when the extension is uninstalled or updated, otherwise NODE_OPTIONS will --require a file that doesn't exist and fail any node commands.

[Tyriar]

Yea. It is dangerous but it's not an area I click very often, so I would feel safe that I wouldn't accidentally click it. The ⚠️ state is also not one that users should want to stay in for very long.

Since the warning should not show up often (maybe when you install new extensions), I think the way to go is to make it a little more difficult to trash your terminal. There may also be additional ways to action it in the future (eg. Don't show again).

[Tyriar]

To accomadate larger env var names and values the plan it to change the hover format to:

Extensions have made changes to this terminal's environment:

VSCODE_GIT_IPC_HANDLE=/tmp/vscode-git-ipc-blah...
FOO=${env:FOO}BAR
BAR=FOO${env:BAR}

#96250

[Tyriar]

To verifier: Do some basic verification of the ExtensionHost.environmentVariableCollection API, no test plan since no changes have really happened since the proposed API was tested.