Describe how to generate graphviz diagrams for dataflow

3 files changed, 20 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/src/img/dataflow-graphviz-example.png b/src/doc/rustc-dev-guide/src/img/dataflow-graphviz-example.png
new file mode 100644
index 00000000000..718411a8c42
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/img/dataflow-graphviz-example.png
Binary files differdiff --git a/src/doc/rustc-dev-guide/src/mir/dataflow.md b/src/doc/rustc-dev-guide/src/mir/dataflow.md
index 5b10afec1f3..be8d4fb9886 100644
--- a/src/doc/rustc-dev-guide/src/mir/dataflow.md
+++ b/src/doc/rustc-dev-guide/src/mir/dataflow.md
@@ -154,8 +154,24 @@ for (bb, block) in body.basic_blocks().iter_enumerated() {
 }
 ```
 
+### Graphviz Diagrams
+
+When the results of a dataflow analysis are not what you expect, it often helps
+to visualize them. This can be done with the `-Zdump-mir` flags described in
+[Debugging MIR]. Start with `-Zdump-mir=F -Zdump-mir-dataflow`, where `F` is
+either "all" or the name of the MIR body you are interested in.
+
+These `.dot` files will be saved in your `mir_dump` directory and will have the
+`NAME` of the analysis (e.g. `maybe_inits`) as part of their filename. Each
+visualization will display the full dataflow state at entry and exit of each
+block, as well as any changes that occur in each statement and terminator.  See
+the example below:
+
+![A graphviz diagram for a dataflow analysis](../img/dataflow-graphviz-example.png)
+
 ["gen-kill" problems]: https://en.wikipedia.org/wiki/Data-flow_analysis#Bit_vector_problems
 [*Static Program Analysis*]: https://cs.au.dk/~amoeller/spa/
+[Debugging MIR]: ./debugging.html
 [`AnalysisDomain`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/dataflow/trait.AnalysisDomain.html
 [`Analysis`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/dataflow/trait.Analysis.html
 [`Engine`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/dataflow/struct.Engine.html
diff --git a/src/doc/rustc-dev-guide/src/mir/debugging.md b/src/doc/rustc-dev-guide/src/mir/debugging.md
index edb68ca7202..3a47a575d59 100644
--- a/src/doc/rustc-dev-guide/src/mir/debugging.md
+++ b/src/doc/rustc-dev-guide/src/mir/debugging.md
@@ -6,6 +6,8 @@ additional output formats, including:
 
 * `-Zdump-mir-graphviz` - dumps a `.dot` file that represents MIR as a
 control-flow graph
+* `-Zdump-mir-dataflow` - dumps a `.dot` file showing the [dataflow state] at
+  each point in the 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).
@@ -87,3 +89,5 @@ rustc.main.002-006.NoLandingPads.before.mir
 that appeared within the `main` function.)
 
 TODO: anything else?
+
+[dataflow state]: ./dataflow.html#graphviz-diagrams