Rollup merge of #119115 - GuillaumeGomez:env-docs, r=Nilstrieb

Update documentation for `--env` compilation flag

Part of https://github.com/rust-lang/rust/issues/80792.
As mentioned in https://github.com/rust-lang/rust/pull/118830.

It adds a mention to `tracked_env::var` and also clarifies what triggers a new compilation.

r? `@Nilstrieb`

1 files changed, 20 insertions, 1 deletions

diff --git a/src/doc/unstable-book/src/compiler-flags/env.md b/src/doc/unstable-book/src/compiler-flags/env.md
index df0547dd24b..ac6d7474a9b 100644
--- a/src/doc/unstable-book/src/compiler-flags/env.md
+++ b/src/doc/unstable-book/src/compiler-flags/env.md
@@ -5,7 +5,11 @@ The tracking issue for this feature is: [#118372](https://github.com/rust-lang/r
 ------------------------
 
 This option flag allows to specify environment variables value at compile time to be
-used by `env!` and `option_env!` macros.
+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-files).
 
 When retrieving an environment variable value, the one specified by `--env` will take
 precedence. For example, if you want have `PATH=a` in your environment and pass:
@@ -20,6 +24,21 @@ Then you will have:
 assert_eq!(env!("PATH"), "env");
 ```
 
+It will trigger a new compilation if any of the `--env` argument value is different.
+So if you first passed:
+
+```bash
+--env A=B --env X=12
+```
+
+and then on next compilation:
+
+```bash
+--env 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