Merge #5202

5202: Runnable env r=matklad a=vsrs

This PR adds on option to specify (in the settings.json) environment variables passed to the runnable.
The simplest way for all runnables in a bunch:
```jsonc
    "rust-analyzer.runnableEnv": {
        "RUN_SLOW_TESTS": "1"
    }
```

Or it is possible to specify vars more granularly:
```jsonc
    "rust-analyzer.runnableEnv": [
        {
            // "mask": null, // null mask means that this rule will be applied for all runnables
            env: {
                 "APP_ID": "1",
                 "APP_DATA": "asdf"
            }
        },
        {
            "mask": "test_name",
            "env": {
                 "APP_ID": "2", // overwrites only APP_ID
            }
        }
    ]
```

You can use any valid RegExp as a mask. Also note that a full runnable name is something like *run bin_or_example_name*, *test some::mod::test_name* or *test-mod some::mod*, so it is possible to distinguish binaries, single tests, and test modules with this masks: `"^run"`, `"^test "` (the trailing space matters!), and `"^test-mod"` respectively.

Fixes #4450

I suppose this info should be somewhere in the docs, but unsure where is the best place.

Co-authored-by: vsrs <[email protected]>

1 files changed, 44 insertions, 12 deletions

diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index b763958fe..7816287e4 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -109,18 +109,6 @@ Here are some useful self-diagnostic commands:
 * To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel.
 * To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools.
 
-==== Special `when` clause context for keybindings.
-You may use `inRustProject` context to configure keybindings for rust projects only. For example:
-[source,json]
-----
-{
-  "key": "ctrl+i",
-  "command": "rust-analyzer.toggleInlayHints",
-  "when": "inRustProject"
-}
-----
-More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
-
 === rust-analyzer Language Server Binary
 
 Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
@@ -337,3 +325,47 @@ They are usually triggered by a shortcut or by clicking a light bulb icon in the
 Cursor position or selection is signified by `┃` character.
 
 include::./generated_assists.adoc[]
+
+== Editor Features
+=== VS Code
+==== Special `when` clause context for keybindings.
+You may use `inRustProject` context to configure keybindings for rust projects only. For example:
+[source,json]
+----
+{
+  "key": "ctrl+i",
+  "command": "rust-analyzer.toggleInlayHints",
+  "when": "inRustProject"
+}
+----
+More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
+
+==== Setting runnable environment variables
+You can use "rust-analyzer.runnableEnv" setting to define runnable environment-specific substitution variables.
+The simplest way for all runnables in a bunch:
+```jsonc
+"rust-analyzer.runnableEnv": {
+    "RUN_SLOW_TESTS": "1"
+}
+```
+
+Or it is possible to specify vars more granularly:
+```jsonc
+"rust-analyzer.runnableEnv": [
+    {
+        // "mask": null, // null mask means that this rule will be applied for all runnables
+        env: {
+             "APP_ID": "1",
+             "APP_DATA": "asdf"
+        }
+    },
+    {
+        "mask": "test_name",
+        "env": {
+             "APP_ID": "2", // overwrites only APP_ID
+        }
+    }
+]
+```
+
+You can use any valid RegExp as a mask. Also note that a full runnable name is something like *run bin_or_example_name*, *test some::mod::test_name* or *test-mod some::mod*, so it is possible to distinguish binaries, single tests, and test modules with this masks: `"^run"`, `"^test "` (the trailing space matters!), and `"^test-mod"` respectively.