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!).
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.
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.
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.
The following steps should serve as a rough guide to add suggestions to suggest-tests
(very welcome!):