Elaborate on dataflow outputs for region constraints

src/SUMMARY.md

@@ -228,6 +228,7 @@
         - [Closure constraints](./borrow-check/region-inference/closure-constraints.md)
         - [Error reporting (stub)](./borrow-check/region-inference/error-reporting.md)
     - [Two-phase-borrows](./borrow-check/two-phase-borrows.md)
+    - [Debugging the borrow checker](./borrow-check/debugging.md)
 - [Closure capture inference](./closure.md)
 - [Async closures/"coroutine-closures"](coroutine-closures.md)
 

src/borrow-check.md

@@ -24,7 +24,7 @@ HIR. Doing borrow checking on MIR has several advantages:
 [47366]: https://github.com/rust-lang/rust/issues/47366
 [nll]: https://rust-lang.github.io/rfcs/2094-nll.html
 
-### Major phases of the borrow checker
+## Major phases of the borrow checker
 
 The borrow checker source is found in
 [the `rustc_borrowck` crate][b_c]. The main entry point is
@@ -57,3 +57,8 @@ the [`mir_borrowck`] query.
   the previous analyses.
 
 [`replace_regions_in_mir`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/nll/fn.replace_regions_in_mir.html
+
+
+## Debugging the borrow checker
+
+See [Debugging the borrow checker](borrow-check/debugging.md) and [MIR Debugging](mir/debugging.md).

src/borrow-check/debugging.md

@@ -0,0 +1,30 @@
+# Debugging the borrow checker
+
+## Region Constraint Graphs and Their Strongly Connected Components
+
+![A graph showing a small number of regions with their outlives relations](../img/region-graphviz.png)
+
+With `-Z dump-mir-graphviz=yes`, you will also get Graphviz files for the outlives constraints
+of the MIR bodies you asked for, as well as the strongly connected components (SCCs) on them.
+They are available as
+`mir_dump/rs-file-name.function-name.-------.nll.0.regioncx.all.dot` and
+`mir_dump/rs-file-name.function-name.-------.nll.0.regioncx.scc.dot` respectively. For both
+graphs, named region variables will be shown with their external name (such as `'static`)
+shown in parenthesis. For region inference variables in universes other than the root universe,
+they will be shown as `/U13` (for universe 13). In the region graph, edges are labelled with
+the MIR location where the relationship is required to hold, or `All` if the constraint should
+always be true.
+
+![A graph showing a small number of strongly connected components on the region-
+outlives-graph above](../img/scc-graphviz.png)
+
+**Note:** There are implicit edges from `'static` to every region, but those are not
+rendered
+in the region graph to avoid clutter. They _do_ however show up in the SCC graph.
+This is why there are outgoing edges from `SCC(5)` in the SCC graph that do not seem
+to have corresponding edges in the region outlives graph above.
+
+## See also
+
+The [general instructions on debugging dataflow](../mir/dataflow.md) also apply to
+graphs generated from borrowcheck data.

src/compiler-debugging.md

@@ -315,7 +315,23 @@ $ dot -T pdf maybe_init_suffix.dot > maybe_init_suffix.pdf
 $ firefox maybe_init_suffix.pdf # Or your favorite pdf viewer
 ```
 
-### Debugging type layouts
+Graphviz also comes with a preprocessor program,
+[`unflatten`](https://graphviz.org/docs/cli/unflatten/), that
+sometimes helps making the outputs look less oddly spread out. It reads
+a dot file and outputs another dot file, so you can use it in a pipe,
+e.g:
+```
+$ unflatten mir_dump/*.foo.-------.nll.0.regioncx.all.dot | dot -Tpdf  -o foo-outlives.pdf
+```
+
+This is particularly useful for complicated region outlives graphs from 
+[the borrow checker](borrow-check/debugging.md).
+
+[An online Graphviz editor and visualiser is
+also available](https://dreampuf.github.io/GraphvizOnline).
+
+
+## Narrowing (Bisecting) Regressions
 
 The internal attribute `#[rustc_dump_layout(...)]` can be used to dump the
 [`Layout`] of the type it is attached to.
@@ -376,6 +392,9 @@ error: aborting due to previous error
 
 [`Layout`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_public/abi/struct.Layout.html
 
+## Debugging borrowcheck
+
+Debugging the borrow checker has [its own chapter](borrow-check/debugging.md).
 
 ## Configuring CodeLLDB for debugging `rustc`