|
1 | 1 | # Suggest tests tool |
2 | 2 |
|
3 | 3 | This chapter is about the internals of and contribution instructions for the |
4 | | -`suggest-tests` tool. For a high-level overview of the tool, see |
5 | | -[this section](../building/suggested.md#x-suggest). This tool is currently in a |
6 | | -beta state and is tracked by [this](https://github.com/rust-lang/rust/issues/109933) |
| 4 | +`suggest-tests` tool. For a high-level overview of the tool, see [this |
| 5 | +section](../building/suggested.md#x-suggest). This tool is currently in a beta |
| 6 | +state and is tracked by [this](https://github.com/rust-lang/rust/issues/109933) |
7 | 7 | issue on Github. Currently the number of tests it will suggest are very limited |
8 | 8 | in scope, we are looking to expand this (contributions welcome!). |
9 | 9 |
|
10 | 10 | ## Internals |
11 | 11 |
|
12 | | -The tool is defined in a separate crate ([`src/tools/suggest-tests`](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests)) |
| 12 | +The tool is defined in a separate crate |
| 13 | +([`src/tools/suggest-tests`](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests)) |
13 | 14 | which outputs suggestions which are parsed by a shim in bootstrap |
14 | 15 | ([`src/bootstrap/src/core/build_steps/suggest.rs`](https://github.com/rust-lang/rust/blob/master/src/bootstrap/src/core/build_steps/suggest.rs)). |
15 | | -The only notable thing the bootstrap shim does is (when invoked with the |
16 | | -`--run` flag) use bootstrap's internal mechanisms to create a new `Builder` and |
17 | | -uses it to invoke the suggested commands. The `suggest-tests` crate is where the |
18 | | -fun happens, two kinds of suggestions are defined: "static" and "dynamic" |
| 16 | +The only notable thing the bootstrap shim does is (when invoked with the `--run` |
| 17 | +flag) use bootstrap's internal mechanisms to create a new `Builder` and uses it |
| 18 | +to invoke the suggested commands. The `suggest-tests` crate is where the fun |
| 19 | +happens, two kinds of suggestions are defined: "static" and "dynamic" |
19 | 20 | suggestions. |
20 | 21 |
|
21 | 22 | ### Static suggestions |
22 | 23 |
|
23 | | -Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/static_suggestions.rs). |
24 | | -Static suggestions are simple: they are just [globs](https://crates.io/crates/glob) |
25 | | -which map to a `x` command. In `suggest-tests`, this is implemented with a |
26 | | -simple `macro_rules` macro. |
| 24 | +Defined |
| 25 | +[here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/static_suggestions.rs). |
| 26 | +Static suggestions are simple: they are just |
| 27 | +[globs](https://crates.io/crates/glob) which map to a `x` command. In |
| 28 | +`suggest-tests`, this is implemented with a simple `macro_rules` macro. |
27 | 29 |
|
28 | 30 | ### Dynamic suggestions |
29 | 31 |
|
30 | | -Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/dynamic_suggestions.rs). |
| 32 | +Defined |
| 33 | +[here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/dynamic_suggestions.rs). |
31 | 34 | These are more complicated than static suggestions and are implemented as |
32 | | -functions with the following signature: `fn(&Path) -> Vec<Suggestion>`. In |
33 | | -other words, each suggestion takes a path to a modified file and (after running |
| 35 | +functions with the following signature: `fn(&Path) -> Vec<Suggestion>`. In other |
| 36 | +words, each suggestion takes a path to a modified file and (after running |
34 | 37 | arbitrary Rust code) can return any number of suggestions, or none. Dynamic |
35 | 38 | suggestions are useful for situations where fine-grained control over |
36 | 39 | suggestions is needed. For example, modifications to the `compiler/xyz/` path |
|
43 | 46 | The following steps should serve as a rough guide to add suggestions to |
44 | 47 | `suggest-tests` (very welcome!): |
45 | 48 |
|
46 | | -1. Determine the rules for your suggestion. Is it simple and operates only on |
47 | | - a single path or does it match globs? Does it need fine-grained control over |
| 49 | +1. Determine the rules for your suggestion. Is it simple and operates only on a |
| 50 | + single path or does it match globs? Does it need fine-grained control over |
48 | 51 | the resulting command or does "one size fit all"? |
49 | 52 | 2. Based on the previous step, decide if your suggestion should be implemented |
50 | 53 | as either static or dynamic. |
51 | 54 | 3. Implement the suggestion. If it is dynamic then a test is highly recommended, |
52 | | - to verify that your logic is correct and to give an example of the suggestion. |
53 | | - See the [tests.rs](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/tests.rs) |
| 55 | + to verify that your logic is correct and to give an example of the |
| 56 | + suggestion. See the |
| 57 | + [tests.rs](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/tests.rs) |
54 | 58 | file. |
55 | 59 | 4. Open a PR implementing your suggestion. **(TODO: add example PR)** |
0 commit comments