src/test/ui/mir-dataflow/README.md

   1 This directory contains unit tests for the MIR-based dataflow
   2 analysis.
   3
   4 These unit tests check the dataflow analysis by embedding calls to a
   5 special `rustc_peek` intrinsic within the code, in tandem with an
   6 attribute `#[rustc_mir(rustc_peek_maybe_init)]` (\*). With that
   7 attribute in place, `rustc_peek` calls are a signal to the compiler to
   8 lookup the computed dataflow state for the Lvalue corresponding to the
   9 argument expression being fed to `rustc_peek`. If the dataflow state
  10 for that Lvalue is a 1-bit at that point in the control flow, then no
  11 error is emitted by the compiler at that point; if it is a 0-bit, then
  12 that invocation of `rustc_peek` will emit an error with the message
  13 "rustc_peek: bit not set".
  14
  15 (\*): Or `#[rustc_mir(rustc_peek_maybe_uninit)]`, and perhaps other
  16 variants in the future.
  17
  18 The end effect is that one can write unit tests for MIR dataflow that
  19 perform simple-queries of the computed dataflow state, and the tests
  20 should be able to be robust in the face of changes to how MIR is
  21 represented or constructed.
  22
  23 ----
  24
  25 Sometimes understanding the dataflow results is difficult without
  26 looking at the actual MIR control-flow graph being processed with the
  27 corresponding GEN and KILL sets.
  28
  29 For a graphviz-rendering with dataflow annotations, add the attribute
  30 `#[rustc_mir(borrowck_graphviz_postflow="/path/to/suffix.dot")]` to
  31 the function in question. (You can change the content of
  32 `"suffix.dot"` to control the filenames used for the output). This
  33 will generate a separate file for each dataflow analysis, adding a
  34 prefix (corresponding to the name of the analysis) to the filename in
  35 each generated output path.
  36
  37  * For example, the above attribute will currently cause two files to
  38    be generated: `/path/to/maybe_init_suffix.dot` and
  39    `/path/to/maybe_uninit_suffix.dot`.
  40
  41  * The generated `.dot` file shows both the computed dataflow results
  42    on *entry* to each block, as well as the gen- and kill-sets that
  43    were so-called "transfer functions" summarizing the effect of each
  44    basic block.
  45
  46  * (In addition to the `borrowck_graphviz_postflow` attribute-key
  47    noted above, there is also `borrowck_graphviz_preflow`; it has the
  48    same interface and generates the same set of files, but it renders
  49    the dataflow state after building the gen- and kill-sets but
  50    *before* running the dataflow analysis itself, so each entry-set is
  51    just the initial default state for that dataflow analysis. This is
  52    less useful for understanding the error message output in these
  53    tests.)