run-make: we should document `cargo()`'s caveats
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
run_make_support exposes a cargo(), which is the stage N cargo[^caveat] 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 rootCargo.tomlvirtual 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 https://github.com/rust-lang/rust/issues/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/rust-lang/rust/issues/134109.
[^caveat]: 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...).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the run_make_support entry point and its cargo() helper, then review how run-make tests are invoked with ./x test run-make --stage=N. Document the listed caveats, including manifest-path, rustc_private, network, and build-time concerns, and link the related issues 128733 and 134109. Done means the guidance is available where contributors look for run-make test documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, testing
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100