run-make: we should document cargo()'s caveats

[jieyouxu]

run_make_support exposes a cargo(), which is the stage N cargo¹ passed when ./x test run-make --stage=N that will exercise the stage N underlying rustc.

Care needs to be taken when using cargo() in run-make tests:

• The test must not build something that uses #[rustc_private] that tries to depend on compiler artifacts used to build the rustc under test or from build artifacts stage0/bootstrap sysroot.
• It needs to pass --manifest-path=.. to its localized cargo package to avoid picking up the source root Cargo.toml virtual manifest.
• There's a current known deficiency that a few run-make tests depend on internet connection (and thus internet connectivity) to build some embedded crates as a smoke test (tracked in run-make: vendor cargo dependencies or external dependencies within the tests #128733). This should generally be avoided, and we ought to be vendoring the crates somehow.
• Care needs to be taken on how long the build goes. For instance, -Zbuild-std=... for all the targets is going to take a long time, and it needs to be carefully evaluated if the run time vs benefit of the test (and its approach) is worth the trade-off.

See also github.com//issues/134109.

Footnotes

1. It depends for COMPILETEST_FORCE_STAGE0=1 ./x test run-make --stage 0... If the user specifies a custom rustc and/or cargo, and this configuration is not very well-supported (may need some kind of //@ ignore-stage-0 on some run-make tests...). ↩