Auto merge of #1949 - RalfJung:miri-lib-src, r=oli-obk

add and document MIRI_LIB_SRC env var to set the source from which Miri builds the standard library

This is just an alias of `XARGO_RUST_SRC`, but avoids exposing how exactly we use xargo.

Author: bors

CONTRIBUTING.md

@@ -107,6 +107,16 @@ There's a test for the cargo wrapper in the `test-cargo-miri` directory; run
 `./run-test.py` in there to execute it. Like `./miri test`, this respects the
 `MIRI_TEST_TARGET` environment variable to execute the test for another target.
 
+### Using a modified standard library
+
+Miri re-builds the standard library into a custom sysroot, so it is fairly easy
+to test Miri against a modified standard library -- you do not even have to
+build Miri yourself, the Miri shipped by `rustup` will work. All you have to do
+is set the `MIRI_LIB_SRC` environment variable to the `library` folder of a
+`rust-lang/rust` repository checkout. Note that changing files in that directory
+does not automatically trigger a re-build of the standard library; you have to
+clear the Miri build cache manually (on Linux, `rm -rf ~/.cache/miri`).
+
 ## Configuring `rust-analyzer`
 
 To configure `rust-analyzer` and VS Code for working on Miri, save the following

README.md

@@ -306,6 +306,12 @@ Moreover, Miri recognizes some environment variables:
   Miri executions, also [see "Testing the Miri driver" in `CONTRIBUTING.md`][testing-miri].
 * `MIRIFLAGS` (recognized by `cargo miri` and the test suite) defines extra
   flags to be passed to Miri.
+* `MIRI_LIB_SRC` defines the directory where Miri expects the sources of the
+  standard library that it will build and use for interpretation. This directory
+  must point to the `library` subdirectory of a `rust-lang/rust` repository
+  checkout. Note that changing files in that directory does not automatically
+  trigger a re-build of the standard library; you have to clear the Miri build
+  cache manually (on Linux, `rm -rf ~/.cache/miri`).
 * `MIRI_SYSROOT` (recognized by `cargo miri` and the test suite)
   indicates the sysroot to use.  To do the same thing with `miri`
   directly, use the `--sysroot` flag.

cargo-miri/bin.rs

@@ -1,5 +1,5 @@
 use std::env;
-use std::ffi::OsString;
+use std::ffi::{OsStr, OsString};
 use std::fmt::Write as _;
 use std::fs::{self, File};
 use std::io::{self, BufRead, BufReader, BufWriter, Read, Write};
@@ -341,8 +341,11 @@ fn setup(subcommand: MiriCommand) {
         ask_to_run(cmd, ask_user, "install a recent enough xargo");
     }
 
-    // Determine where the rust sources are located.  `XARGO_RUST_SRC` env var trumps everything.
-    let rust_src = match std::env::var_os("XARGO_RUST_SRC") {
+    // Determine where the rust sources are located.  The env vars manually setting the source
+    // (`MIRI_LIB_SRC`, `XARGO_RUST_SRC`) trump auto-detection.
+    let rust_src_env_var =
+        std::env::var_os("MIRI_LIB_SRC").or_else(|| std::env::var_os("XARGO_RUST_SRC"));
+    let rust_src = match rust_src_env_var {
         Some(path) => {
             let path = PathBuf::from(path);
             // Make path absolute if possible.
@@ -376,6 +379,13 @@ fn setup(subcommand: MiriCommand) {
     if !rust_src.exists() {
         show_error(format!("given Rust source directory `{}` does not exist.", rust_src.display()));
     }
+    if rust_src.file_name().and_then(OsStr::to_str) != Some("library") {
+        show_error(format!(
+            "given Rust source directory `{}` does not seem to be the `library` subdirectory of \
+             a Rust source checkout.",
+            rust_src.display()
+        ));
+    }
 
     // Next, we need our own libstd. Prepare a xargo project for that purpose.
     // We will do this work in whatever is a good cache dir for this platform.