run-make: add some basic docs about the test suite's setup

Author: jieyouxu

tests/run-make/README.md

@@ -0,0 +1,35 @@
+# The `run-make` test suite
+
+The `run-make` test suite contain tests which are the most flexible out of all
+the [rust-lang/rust](https://github.com/rust-lang/rust) test suites. `run-make`
+tests can basically contain arbitrary code, and are supported by the
+[`run_make_support`] library.
+
+## Infrastructure
+
+The implementation for collecting and building the `rmake.rs` recipes (or
+`Makefile`s) are in
+[`src/tools/compiletest/src/runtest.rs`](https://github.com/rust-lang/rust/blob/master/src/tools/compiletest/src/runtest.rs),
+in `run_rmake_v2_test` and `run_rmake_legacy_test`.
+
+### Rust-based `run-make` tests: `rmake.rs`
+
+The setup for the `rmake.rs` version is a 3-stage process:
+
+1. First, we build the [`run_make_support`] library in bootstrap as a tool lib.
+2. Then, we compile the `rmake.rs` "recipe" linking the support library and its
+   dependencies in, and provide a bunch of env vars. We setup a directory
+   structure
+
+   ```
+   test_specific_build_dir/
+       rmake.exe              # recipe binary
+       rmake_out/             # sources from test sources copied over
+   ```
+
+   and copy non-`rmake.rs` input support files over to `rmake_out/`. The
+   support library is made available as an [*extern prelude*][extern_prelude].
+3. Finally, we run the recipe binary and set `rmake_out/` as the CWD.
+
+[`run_make_support`]: https://github.com/rust-lang/rust/tree/master/src/tools/run-make-support
+[extern_prelude]: https://doc.rust-lang.org/reference/names/preludes.html#extern-prelude