Stabilize --env-set option

compiler/rustc_session/src/config.rs

@@ -1827,7 +1827,7 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
             "Remap source names in all output (compiler messages and output files)",
             "FROM=TO",
         ),
-        opt::multi("", "env-set", "Inject an environment variable", "VAR=VALUE"),
+        opt::multi_s("", "env-set", "Inject an environment variable", "VAR=VALUE"),
     ]);
     opts
 }

src/doc/rustc/src/command-line-arguments.md

@@ -504,3 +504,47 @@ an empty option. The file can use Unix or Windows style line endings, and must b
 encoded as UTF-8.
 
 [the JSON chapter]: json.md
+
+<a id="option-env-set"></a>
+## `env-set`: inject an environment variable
+
+This option flag allows to specify environment variables value at compile time to be
+used by `env!` and `option_env!` macros. It also impacts `tracked_env::var` function
+from the `proc_macro` crate.
+
+This information will be stored in the dep-info files. For more information about
+dep-info files, take a look [here](https://doc.rust-lang.org/cargo/guide/build-cache.html#dep-info-file\
+s).
+
+When retrieving an environment variable value, the one specified by `--env-set` will take
+precedence. For example, if you want have `PATH=a` in your environment and pass:
+
+```bash
+rustc --env-set PATH=env
+```
+
+Then you will have:
+
+```rust,no_run
+assert_eq!(env!("PATH"), "env");
+```
+
+It will trigger a new compilation if any of the `--env-set` argument value is different.
+So if you first passed:
+
+```bash
+--env-set A=B --env X=12
+```
+
+and then on next compilation:
+
+```bash
+--env-set A=B
+```
+
+`X` value is different (not set) so the code will be re-compiled.
+
+Please note that on Windows, environment variables are case insensitive but case
+preserving whereas `rustc`'s environment variables are case sensitive. For example,
+having `Path` in your environment (case insensitive) is different than using
+`rustc --env-set Path=...` (case sensitive).

tests/ui/extenv/extenv-env-overload.rs

@@ -1,6 +1,6 @@
 // run-pass
 // rustc-env:MY_VAR=tadam
-// compile-flags: --env-set MY_VAR=123abc -Zunstable-options
+// compile-flags: --env-set MY_VAR=123abc
 
 // This test ensures that variables provided with `--env` take precedence over
 // variables from environment.

tests/ui/extenv/extenv-env.rs

@@ -1,4 +1,4 @@
-// compile-flags: --env-set FOO=123abc -Zunstable-options
+// compile-flags: --env-set FOO=123abc
 // run-pass
 fn main() {
     assert_eq!(env!("FOO"), "123abc");

tests/ui/proc-macro/env.rs

@@ -1,7 +1,7 @@
 // aux-build:env.rs
 // run-pass
 // rustc-env: THE_CONST=1
-// compile-flags: -Zunstable-options --env-set THE_CONST=12 --env-set ANOTHER=4
+// compile-flags: --env-set THE_CONST=12 --env-set ANOTHER=4
 
 #![crate_name = "foo"]