src/test/mir-opt/README.md

   1 This folder contains tests for MIR optimizations.
   2
   3 The test format is:
   4
   5 ```
   6 (arbitrary rust code)
   7 // END RUST SOURCE
   8 // START $file_name_of_some_mir_dump_0
   9 //  $expected_line_0
  10 // (lines or elision)
  11 // $expected_line_N
  12 // END $file_name_of_some_mir_dump_0
  13 // (lines or elision)
  14 // START $file_name_of_some_mir_dump_N
  15 //  $expected_line_0
  16 // (lines or elision)
  17 // $expected_line_N
  18 // END $file_name_of_some_mir_dump_N
  19 ```
  20
  21 All the test information is in comments so the test is runnable.
  22
  23 For each $file_name, compiletest expects [$expected_line_0, ...,
  24 $expected_line_N] to appear in the dumped MIR in order.  Currently it allows
  25 other non-matched lines before and after, but not between $expected_lines,
  26 should you want to skip lines, you must include an elision comment, of the form
  27 (as a regex) `//\s*...\s*`. The lines will be skipped lazily, that is, if there
  28 are two identical lines in the output that match the line after the elision
  29 comment, the first one wil be matched.
  30
  31 Examples:
  32
  33 The following blocks will not match the one after it.
  34
  35 ```
  36 bb0: {
  37     StorageLive(_1);
  38     _1 = const true;
  39     StorageDead(_1);
  40 }
  41 ```
  42
  43 ```
  44 bb0: {
  45     StorageLive(_1);
  46     _1 = const true;
  47     goto -> bb1
  48 }
  49 bb1: {
  50     StorageDead(_1);
  51     return;
  52 }
  53 ```
  54
  55 But this will match the one above,
  56
  57 ```
  58 bb0: {
  59     StorageLive(_1);
  60     _1 = const true;
  61     ...
  62     StorageDead(_1);
  63     ...
  64 }
  65 ```
  66
  67 Lines match ignoring whitespace, and the prefix "//" is removed.
  68
  69 It also currently strips trailing comments -- partly because the full file path
  70 in "scope comments" is unpredictable and partly because tidy complains about
  71 the lines being too long.
  72
  73 compiletest handles dumping the MIR before and after every pass for you.  The
  74 test writer only has to specify the file names of the dumped files (not the
  75 full path to the file) and what lines to expect.  There is an option to rustc
  76 that tells it to dump the mir into some directly (rather then always dumping to
  77 the current directory).