document environment variables used when building the compiler

[vitiral]

document environment variables used when building the compiler

[petrochenkov]

Most of the listed variables are used by the build system and test suite, not compiler itself.
Many of them are also implementation details (they are both set and read internally) that are not supposed to be set from the outside of rustbuild.

(P.S. I suspect the meaning of many of internal variables could could be more clear if naming schemes were more explicit and consistent, e.g. everything used by bootstrap/bin/rustc.rs could be prefixed with RUSTC_WRAPPER_, bootstrap/bin/rustdoc.rs - RUSTDOC_WRAPPER_, etc.)

[pnkfelix]

There was some semi-recent discussion bemoaning the compilers undiscoverable environment variables; I suggested there that it might be a good idea to extend the rustc --help -v output to include a section dedicated to environment variables.

[vitiral]

Note: I believe this is dfferent from rust-lang/rust#44074, as this is concerned with the environment variables used for building the compiler itself, not the environment variables that the compiler uses.

However, stage0 probably makes use of the latter. I'm not sure how to manage the fact that those are related -- we probably need to document both.

rust-lang/rust#44074 also brings up the env! macro. Please let me know if there are other ways to get environment variables than env::var(_os) (rust) and os.environ.get (python). Hopefully we don't have too many bash scripts, as it would just look like plain old variables there...

[theotherjimmy]

the rustc and libdir variables appear to be "RUSTC_STAGE", "RUSTC_REAL", "RUSTC_SNAPSHOT_LIBDIR", "RUSTC_LIBDIR"

    let (rustc, libdir) = if target.is_none() && version.is_none() {
        ("RUSTC_SNAPSHOT", "RUSTC_SNAPSHOT_LIBDIR")
    } else {
        ("RUSTC_REAL", "RUSTC_LIBDIR")
    };
    let stage = env::var("RUSTC_STAGE").expect("RUSTC_STAGE was not set");
    let sysroot = env::var_os("RUSTC_SYSROOT").expect("RUSTC_SYSROOT was not set");
    let mut on_fail = env::var_os("RUSTC_ON_FAIL").map(|of| Command::new(of));

    let rustc = env::var_os(rustc).unwrap_or_else(|| panic!("{:?} was not set", rustc));
    let libdir = env::var_os(libdir).unwrap_or_else(|| panic!("{:?} was not set", libdir));
    let mut dylib_path = bootstrap::util::dylib_path();
    dylib_path.insert(0, PathBuf::from(libdir));

    let mut cmd = Command::new(rustc);
    cmd.args(&args)

[retep998]

Also be wary of code that does use std::env::var; and uses it simply as var.

[steveklabnik]

Triage: we now have a home for this kind of information https://doc.rust-lang.org/rustc/

[pnkfelix]

(But in practice if we want such a list to be kept up to date, we'll need an API for defining the environment variables in active use by the compiler, much the same way that we define e.g. command line switches via a standard API...)

[mark-i-m]

Has there been any progress on this?

[mark-i-m]

Fyi

https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/env.20vars.20and.20x.2Epy.20.2338686

[jyn514]

Most of the listed variables are used by the build system and test suite, not compiler itself.
Many of them are also implementation details (they are both set and read internally) that are not supposed to be set from the outside of rustbuild.

I agree with this. Given that we document how to replicate the environment variables for a given run (https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html#environment-variables) I don't think it's important to document the variables themselves - the supported interface here is config.toml, not the env vars. If we were going to document this it would live in src/bootstrap/README.md anyway, not the external facing docs.