llvm/utils/TableGen/jupyter/LLVM_TableGen.md

   1 # LLVM TableGen Kernel
   2
   3 This notebook is running `llvm-tblgen`.
   4
   5
   6 ```tablegen
   7 %reset
   8 // This is some tablegen
   9 class Foo {}
  10 ```
  11
  12     ------------- Classes -----------------
  13     class Foo {
  14     }
  15     ------------- Defs -----------------
  16
  17
  18 Errors printed to stderr are shown.
  19
  20
  21 ```tablegen
  22 %reset
  23 This is not tablegen.
  24 ```
  25
  26     <stdin>:1:1: error: Unexpected token at top level
  27     This is not tablegen.
  28     ^
  29
  30
  31 Add some classes to get some output.
  32
  33
  34 ```tablegen
  35 %reset
  36 class Stuff {}
  37 def thing : Stuff {}
  38 ```
  39
  40     ------------- Classes -----------------
  41     class Stuff {
  42     }
  43     ------------- Defs -----------------
  44     def thing { // Stuff
  45     }
  46
  47
  48 By default cells are connected. Meaning that we cache the code and magic directives from the previously run cells.
  49
  50 This means that the next cell still sees the `Stuff` class.
  51
  52
  53 ```tablegen
  54 def other_thing : Stuff {}
  55 ```
  56
  57     ------------- Classes -----------------
  58     class Stuff {
  59     }
  60     ------------- Defs -----------------
  61     def other_thing {   // Stuff
  62     }
  63     def thing { // Stuff
  64     }
  65
  66
  67 You can use the magic `%reset` to clear this cache and start fresh.
  68
  69
  70 ```tablegen
  71 %reset
  72 def other_thing : Stuff {}
  73 ```
  74
  75     <stdin>:1:19: error: Couldn't find class 'Stuff'
  76     def other_thing : Stuff {}
  77                       ^
  78
  79
  80 You can also configure the default reset behaviour using the `%config` magic.
  81
  82
  83 ```tablegen
  84 %config cellreset on
  85 class Thing {}
  86 ```
  87
  88     ------------- Classes -----------------
  89     class Thing {
  90     }
  91     ------------- Defs -----------------
  92
  93
  94
  95 ```tablegen
  96 // The cache is reset here so this is an error.
  97 def AThing: Thing {}
  98 ```
  99
 100     <stdin>:2:13: error: Couldn't find class 'Thing'
 101     def AThing: Thing {}
 102                 ^
 103
 104
 105 The default value is `off`, meaning cells are connected. If you want to override the default for one cell only, use the `%reset` or `%noreset` magic. These always override the default.
 106
 107
 108 ```tablegen
 109 class Thing {}
 110 ```
 111
 112     ------------- Classes -----------------
 113     class Thing {
 114     }
 115     ------------- Defs -----------------
 116
 117
 118
 119 ```tablegen
 120 %noreset
 121 // This works because of the noreset above.
 122 def AThing: Thing {}
 123 ```
 124
 125     ------------- Classes -----------------
 126     class Thing {
 127     }
 128     ------------- Defs -----------------
 129     def AThing {        // Thing
 130     }
 131
 132
 133
 134 ```tablegen
 135 // This does not because we're not changing the default.
 136 def AnotherThing: Thing {}
 137 ```
 138
 139     <stdin>:2:19: error: Couldn't find class 'Thing'
 140     def AnotherThing: Thing {}
 141                       ^
 142
 143
 144
 145 ```tablegen
 146 %config cellreset off
 147 %reset
 148 // Here we have an empty cache and default reset behaviour.
 149 ```
 150
 151     ------------- Classes -----------------
 152     ------------- Defs -----------------
 153
 154
 155 It is not valid to have `%reset` and `%noreset` in the same cell.
 156
 157
 158 ```tablegen
 159 %reset
 160 %noreset
 161 ```
 162
 163     %reset and %noreset in the same cell is not allowed. Use only one, or neither.
 164
 165 Consider setting `cellreset` to the majority usecase for your notebook. For example a tutorial building a large example across many cells will likely want it `off`. One with many standalone examples, `on`.
 166
 167 There is a "magic" directive `%args` that you can use to send command line arguments to `llvm-tblgen`.
 168
 169 For example, here we have some code that shows a warning.
 170
 171
 172 ```tablegen
 173 %reset
 174 class Thing <int A, int B> {
 175     int num = A;
 176 }
 177 ```
 178
 179     <stdin>:1:25: warning: unused template argument: Thing:B
 180     class Thing <int A, int B> {
 181                             ^
 182
 183
 184 We can pass an argument to ignore that warning.
 185
 186
 187 ```tablegen
 188 %args --no-warn-on-unused-template-args
 189 ```
 190
 191     ------------- Classes -----------------
 192     class Thing<int Thing:A = ?, int Thing:B = ?> {
 193       int num = Thing:A;
 194     }
 195     ------------- Defs -----------------
 196
 197
 198 If you have a run of cells without a `%reset`, the most recent `%args` is used.
 199
 200
 201 ```tablegen
 202 // This passes --no-warn-on-unused-template-args
 203 ```
 204
 205     ------------- Classes -----------------
 206     class Thing<int Thing:A = ?, int Thing:B = ?> {
 207       int num = Thing:A;
 208     }
 209     ------------- Defs -----------------
 210
 211
 212
 213 ```tablegen
 214 %args
 215 // Now we're not passing the argument so the warning comes back.
 216 ```
 217
 218     <stdin>:1:25: warning: unused template argument: Thing:B
 219     class Thing <int A, int B> {
 220                             ^
 221
 222
 223 If there are many `%args` in a cell, the last one is used.
 224
 225
 226 ```tablegen
 227 %reset
 228 %args --no-warn-on-unused-template-args
 229 %args
 230 class Thing <int A, int B> {}
 231 ```
 232
 233     <stdin>:1:18: warning: unused template argument: Thing:A
 234     class Thing <int A, int B> {}
 235                      ^
 236     <stdin>:1:25: warning: unused template argument: Thing:B
 237     class Thing <int A, int B> {}
 238                             ^
 239