Describe how to generate graphviz diagrams for dataflow

Author: ecstatic-morse

src/img/dataflow-graphviz-example.png

@@ -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

src/mir/dataflow.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