Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds documentation to cover spanview output #844

Merged
merged 1 commit into from
Sep 2, 2020
Merged

Adds documentation to cover spanview output #844

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions src/compiler-debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,24 @@ $ dot -T pdf maybe_init_suffix.dot > maybe_init_suffix.pdf
$ firefox maybe_init_suffix.pdf # Or your favorite pdf viewer
```

## Viewing Spanview output (.html files)
[viewing-spanview-output]: #viewing-spanview-output

In addition to [graphviz output](#formatting-graphviz-output), MIR debugging
flags include an option to generate a MIR representation called `Spanview` that
uses HTML to highlight code regions in the original source code and display
compiler metadata associated with each region.
[`-Zdump-mir-spanview`](./mir/debugging.md), for example, highlights spans
associated with each MIR `Statement`, `Terminator`, and/or `BasicBlock`.

These `.html` files use CSS features to dynamically expand spans obscured by
overlapping spans, and native tooltips (based on the HTML `title` attribute) to
reveal the actual MIR elements, as text.

To view these files, simply use a modern browser, or a CSS-capable HTML preview
feature in a modern IDE. (The default HTML preview pane in *VS Code* is known to
work, for instance.

## Narrowing (Bisecting) Regressions

The [cargo-bisect-rustc][bisect] tool can be used as a quick and easy way to
Expand Down
14 changes: 11 additions & 3 deletions src/mir/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,16 @@
# MIR Debugging

The `-Zdump-mir` flag can be used to dump a text representation of the MIR. The
`-Zdump-mir-graphviz` flag can be used to dump a `.dot` file that represents
MIR as a control-flow graph.
The `-Zdump-mir` flag can be used to dump a text representation of the MIR.
The following optional flags, used in combination with `-Zdump-mir`, enable
additional output formats, including:

* `-Zdump-mir-graphviz` - dumps a `.dot` file that represents MIR as a
control-flow graph
* `-Zdump-mir-spanview` - dumps an `.html` file that highlights the source
spans associated with MIR elements (including mouse-over actions to reveal
elements obscured by overlaps, and tooltips to view the MIR statements).
This flag takes an optional value: `statement` (the default), `terminator`, or
`block`, to generate span highlights with different levels of granulatity.

`-Zdump-mir=F` is a handy compiler options that will let you view the MIR for
each function at each stage of compilation. `-Zdump-mir` takes a **filter** `F`
Expand Down