Remove outdated references to coverage debug code (#1797)
This commit is contained in:
Stuart Cook
GitHub
parent
6b4bf70c2a
commit
c9eae9076d
Binary file not shown.
|
Before Width: | Height: | Size: 332 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 313 KiB |
|
|
@ -335,20 +335,14 @@ The `Instrumentor`'s `inject_counters()` uses the `CoverageGraph` to
|
|||
compute the best places to inject coverage counters, as MIR `Statement`s,
|
||||
with the following steps:
|
||||
|
||||
1. Depending on the debugging configurations in `rustc`'s, `config.toml`,
|
||||
and `rustc` command line flags, various debugging features may be enabled
|
||||
to enhance `debug!()` messages in logs, and to generate various "dump" files,
|
||||
to help developers understand the MIR transformation process for coverage.
|
||||
Most of the debugging features are implemented in the [`debug`][debug]
|
||||
sub-module.
|
||||
2. [`generate_coverage_spans()`][generate-coverage-spans] computes the minimum set of distinct,
|
||||
1. [`generate_coverage_spans()`][generate-coverage-spans] computes the minimum set of distinct,
|
||||
non-branching code regions, from the MIR. These `CoverageSpan`s
|
||||
represent a span of code that must be counted.
|
||||
3. [`make_bcb_counters()`][make-bcb-counters] generates `CoverageKind::Counter`s and
|
||||
2. [`make_bcb_counters()`][make-bcb-counters] generates `CoverageKind::Counter`s and
|
||||
`CoverageKind::Expression`s for each `CoverageSpan`, plus additional
|
||||
`intermediate_expressions`[^intermediate-expressions], not associated with any `CodeRegion`, but
|
||||
are required to compute a final `Expression` value for a `CodeRegion`.
|
||||
4. Inject the new counters into the MIR, as new `StatementKind::Coverage`
|
||||
3. Inject the new counters into the MIR, as new `StatementKind::Coverage`
|
||||
statements. This is done by three distinct functions:
|
||||
- `inject_coverage_span_counters()`
|
||||
- `inject_indirect_counters()`
|
||||
|
|
@ -420,66 +414,12 @@ The BCB CFG is critical to simplifying the coverage analysis by ensuring graph p
|
|||
queries (`is_dominated_by()`, `predecessors`, `successors`, etc.) have branch (control flow)
|
||||
significance.
|
||||
|
||||
To visualize the `CoverageGraph`, you can generate a _graphviz_ `*.dot`
|
||||
file with the following `rustc` flags:[^graphviz-dark-mode]
|
||||
|
||||
[^graphviz-dark-mode]: This image also applies `-Z graphviz-dark-mode`, to
|
||||
produce a Graphviz document with "dark mode" styling. If you use a dark mode or
|
||||
theme in your development environment, you will probably want to use this
|
||||
option so you can review the graphviz output without straining your vision.
|
||||
|
||||
```shell
|
||||
$ rustc -C instrument-coverage -Z dump-mir=InstrumentCoverage \
|
||||
-Z dump-mir-graphviz some_rust_source.rs
|
||||
```
|
||||
|
||||
The `-Z dump-mir` flag requests [MIR debugging
|
||||
output][mir-debugging] (generating `*.mir` files, by default).
|
||||
`-Z dump-mir-graphviz` additionally generates `*.dot` files.
|
||||
`-Z dump-mir=InstrumentCoverage` restricts these files to the
|
||||
`InstrumentCoverage` pass. All files are written to the `./mir_dump/`
|
||||
directory, by default.
|
||||
|
||||
Files with names ending in `.-------.InstrumentCoverage.0.dot` contain the
|
||||
_graphviz_ representations of a `CoverageGraph` (one for each MIR, that is,
|
||||
for each function and closure):
|
||||
|
||||
<img alt="cropped image of a sample CoverageGraph in graphviz format"
|
||||
src="img/coverage-graphviz-01.png" style="border: 1px solid gray" class="center"/>
|
||||
<br/>
|
||||
|
||||
This image shows each `BasicCoverageBlock` as a rectangular _node_, with
|
||||
directional edges (the arrows) leading from each node to its `successors()`.
|
||||
The nodes contain information in sections:
|
||||
|
||||
1. The gray header has a label showing the BCB ID (or _index_ for looking up
|
||||
its `BasicCoverageBlockData`).
|
||||
2. The first content section shows the assigned `Counter` or `Expression` for
|
||||
each contiguous section of code. (There may be more than one `Expression`
|
||||
incremented by the same `Counter` for noncontiguous sections of code
|
||||
representing the same sequential actions.) Note the code is represented by
|
||||
the line and column ranges (for example: `52:28-52:33`, representing the
|
||||
original source line 52, for columns 28-33). These are followed by the MIR
|
||||
`Statement` or `Terminator` represented by that source range. (How these
|
||||
coverage regions are determined is discussed in the following section.)
|
||||
3. The final section(s) show the MIR `BasicBlock`s (by ID/index and its
|
||||
`TerminatorKind`) contained in this BCB. The last BCB is separated out
|
||||
because its `successors()` determine the edges leading out of the BCB, and
|
||||
into the `leading_bb()` (first `BasicBlock`) of each successor BCB.
|
||||
|
||||
Note, to find the `BasicCoverageBlock` from a final BCB `Terminator`'s
|
||||
successor `BasicBlock`, there is an index and helper
|
||||
function--[`bcb_from_bb()`][bcb-from-bb]--to look up a `BasicCoverageBlock` from
|
||||
*any* contained `BasicBlock`.
|
||||
|
||||
[directed-graph]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/graph/trait.DirectedGraph.html
|
||||
[graph-traits]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/graph/index.html#traits
|
||||
[mir-dev-guide]: mir/index.md
|
||||
[compute-basic-coverage-blocks]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/graph/struct.CoverageGraph.html#method.compute_basic_coverage_blocks
|
||||
[simplify-cfg]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/simplify/enum.SimplifyCfg.html
|
||||
[rust-lang/rust#78544]: https://github.com/rust-lang/rust/issues/78544
|
||||
[mir-debugging]: mir/debugging.md
|
||||
[bcb-from-bb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/graph/struct.CoverageGraph.html#method.bcb_from_bb
|
||||
|
||||
### `CoverageSpans`
|
||||
|
||||
|
|
@ -498,32 +438,6 @@ The final stage of `generate_coverage_spans()` is handled by
|
|||
merges and de-duplicates them, and returns an optimal, minimal set of `CoverageSpan`s
|
||||
that can be used to assign coverage `Counter`s or `Expression`s, one-for-one.
|
||||
|
||||
An visual, interactive representation of the final `CoverageSpan`s can be
|
||||
generated with the following `rustc` flags:
|
||||
|
||||
```shell
|
||||
$ rustc -C instrument-coverage -Z dump-mir=InstrumentCoverage \
|
||||
-Z dump-mir-spanview some_rust_source.rs
|
||||
```
|
||||
|
||||
These flags request Spanview output for the `InstrumentCoverage` pass, and the
|
||||
resulting files (one for each MIR, that is, for each function or closure) can be
|
||||
found in the `mir_dump` directory (by default), with the extension:
|
||||
`.-------.InstrumentCoverage.0.html`.
|
||||
|
||||
<img alt="cropped image of a sample Spanview in a browser"
|
||||
src="img/coverage-spanview-01.png" style="border: 1px solid gray" class="center"/>
|
||||
<br/>
|
||||
|
||||
The image above shows one such example. The orange and blue backgrounds
|
||||
highlight alternating `CoverageSpan`s from the refined set. Hovering over a
|
||||
line expands the output on that line to show the MIR `BasicBlock` IDs covered
|
||||
by each `CoverageSpan`. While hovering, the `CoverageSpan` under the pointer
|
||||
also has a _tooltip_ block of text, showing even more detail, including the
|
||||
MIR `Statement`s and `Terminator`s contributing to the `CoverageSpan`, and
|
||||
their individual `Span`s (which should be encapsulated within the code region
|
||||
of the refined `CoverageSpan`)
|
||||
|
||||
[coverage-spans]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/spans/struct.CoverageSpans.html
|
||||
[coverage-span]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/spans/struct.CoverageSpan.html
|
||||
[to-refined-spans]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/spans/struct.CoverageSpans.html#method.to_refined_spans
|
||||
|
|
@ -622,12 +536,3 @@ so the counter is only incremented when traversing the branch edge.
|
|||
[inject-coverage-span-counters]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/struct.Instrumentor.html#method.inject_coverage_span_counters
|
||||
[inject-indirect-counters]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/struct.Instrumentor.html#method.inject_indirect_counters
|
||||
[inject-intermediate-expression]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/fn.inject_intermediate_expression.html
|
||||
|
||||
### Additional Debugging Support
|
||||
|
||||
See the
|
||||
[crate documentation for `rustc_mir::transform::coverage::debug`][coverage-debugging]
|
||||
for a detailed description of the debug output, logging, and configuration options
|
||||
available to developers working on the `InstrumentCoverage` pass.
|
||||
|
||||
[coverage-debugging]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/debug/index.html
|
||||
|
|
|
|||
Loading…
Reference in New Issue