rust-lang/rust · critical

REAL_LIBRARY_PATH_VAR

Error message

REAL_LIBRARY_PATH_VAR

What it means

Thrown by restore_library_path (build.rs:54-65) via `.expect("REAL_LIBRARY_PATH_VAR")` when reading the env var of the same name. rustc_llvm's build.rs needs to undo Cargo's injection of the compiler's dylib path into the library search path (comment block at build.rs:46-53); bootstrap sets REAL_LIBRARY_PATH_VAR and REAL_LIBRARY_PATH to the values it observed before Cargo mutated the environment. If the var is absent, the contract with bootstrap has been broken and the build script panics.

Source

Thrown at compiler/rustc_llvm/build.rs:55

    // Force the link mode we want, preferring static by default, but
    // possibly overridden by `configure --enable-llvm-link-shared`.
    if tracked_env_var_os("LLVM_LINK_SHARED").is_some() {
        ("dylib", "--link-shared")
    } else {
        ("static", "--link-static")
    }
}

// Because Cargo adds the compiler's dylib path to our library search path, llvm-config may
// break: the dylib path for the compiler, as of this writing, contains a copy of the LLVM
// shared library, which means that when our freshly built llvm-config goes to load it's
// associated LLVM, it actually loads the compiler's LLVM. In particular when building the first
// compiler (i.e., in stage 0) that's a problem, as the compiler's LLVM is likely different from
// the one we want to use. As such, we restore the environment to what bootstrap saw. This isn't
// perfect -- we might actually want to see something from Cargo's added library paths -- but
// for now it works.
fn restore_library_path() {
    let key = tracked_env_var_os("REAL_LIBRARY_PATH_VAR").expect("REAL_LIBRARY_PATH_VAR");
    if let Some(env) = tracked_env_var_os("REAL_LIBRARY_PATH") {
        unsafe {
            env::set_var(&key, env);
        }
    } else {
        unsafe {
            env::remove_var(&key);
        }
    }
}

/// Reads an environment variable and adds it to dependencies.
/// Supposed to be used for all variables except those set for build scripts by cargo
/// <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts>
fn tracked_env_var_os<K: AsRef<OsStr> + Display>(key: K) -> Option<OsString> {
    println!("cargo:rerun-if-env-changed={key}");
    env::var_os(key)
}

View on GitHub (pinned to 22057b88b0)

Solutions

1. Always build rustc_llvm through bootstrap: `./x.py build` (or the equivalent `./x.py build compiler/rustc_llvm`), which sets REAL_LIBRARY_PATH_VAR.
2. If invoking the build script manually for debugging, set REAL_LIBRARY_PATH_VAR (and usually REAL_LIBRARY_PATH) to the correct dylib search-path variable name for the platform, e.g. LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS.
3. Update your bootstrap checkout to match the rustc source version you are building, since the variable contract is version-coupled.

# Pre-build: reject targets without a known REAL_LIBRARY_PATH_VAR mapping
case "$TARGET" in
  *-linux-*|*-apple-darwin*|*-windows-*) : ;;
  *) echo "unsupported target for rustc_llvm library path mapping"; exit 1 ;;
esac

When it happens

Trigger: Building rustc_llvm outside of bootstrap (./x.py), e.g. by running `cargo build` directly in compiler/rustc_llvm, which does not export REAL_LIBRARY_PATH_VAR. Also reproducible if bootstrap's env-passing is bypassed or a custom build wrapper strips environment variables before invoking the build script.

Common situations: Trying to build a single rustc crate by hand with cargo rather than through `./x.py build`; CI environments that sanitize or drop inherited environment; mismatched bootstrap/tool versions where the bootstrap binary does not set this var.

Related errors

• LLVM_CONFIG was not set
• command did not execute successfully: {:?} expected success,
• wrong command used for building
• TARGET was not set
• HOST was not set

AI-assisted analysis of rust-lang/rust@22057b88b0 (2026-08-03). Data as JSON: /data/errors/eaa0c189f576ee7b.json. Report an issue: GitHub.