Suggest tests tool
This chapter is about the internals of and contribution instructions for the
suggest-tests tool. For a high-level overview of the tool, see
this section. This tool is currently in a
beta state and is tracked by this
issue on Github. Currently the number of tests it will suggest are very limited
in scope, we are looking to expand this (contributions welcome!).
Internals
The tool is defined in a separate crate (src/tools/suggest-tests)
which outputs suggestions which are parsed by a shim in bootstrap
(src/bootstrap/src/core/build_steps/suggest.rs).
The only notable thing the bootstrap shim does is (when invoked with the
--run flag) use bootstrap's internal mechanisms to create a new Builder and
uses it to invoke the suggested commands. The suggest-tests crate is where the
fun happens, two kinds of suggestions are defined: "static" and "dynamic"
suggestions.
Static suggestions
Defined here.
Static suggestions are simple: they are just globs
which map to a x command. In suggest-tests, this is implemented with a
simple macro_rules macro.
Dynamic suggestions
Defined here.
These are more complicated than static suggestions and are implemented as
functions with the following signature: fn(&Path) -> Vec<Suggestion>. In
other words, each suggestion takes a path to a modified file and (after running
arbitrary Rust code) can return any number of suggestions, or none. Dynamic
suggestions are useful for situations where fine-grained control over
suggestions is needed. For example, modifications to the compiler/xyz/ path
should trigger the x test compiler/xyz suggestion. In the future, dynamic
suggestions might even read file contents to determine if (what) tests should
run.
Adding a suggestion
The following steps should serve as a rough guide to add suggestions to
suggest-tests (very welcome!):
- Determine the rules for your suggestion. Is it simple and operates only on a single path or does it match globs? Does it need fine-grained control over the resulting command or does "one size fit all"?
- Based on the previous step, decide if your suggestion should be implemented as either static or dynamic.
- Implement the suggestion. If it is dynamic then a test is highly recommended, to verify that your logic is correct and to give an example of the suggestion. See the tests.rs file.
- Open a PR implementing your suggestion. (TODO: add example PR)