llvm/utils/TableGen/README.md

   1 # LLVM TableGen
   2
   3 The purpose of TableGen is to generate complex output files based on information
   4 from source files that are significantly easier to code than the output files would be, and also easier to maintain and modify over time.
   5
   6 The information is coded in a declarative style involving classes and records,
   7 which are then processed by TableGen.
   8
   9 ```
  10 class Hello <string _msg> {
  11   string msg = !strconcat("Hello ", _msg);
  12 }
  13
  14 def HelloWorld: Hello<"world!"> {}
  15 ```
  16 ```
  17 ------------- Classes -----------------
  18 class Hello<string Hello:_msg = ?> {
  19   string msg = !strconcat("Hello ", Hello:_msg);
  20 }
  21 ------------- Defs -----------------
  22 def HelloWorld {        // Hello
  23   string msg = "Hello world!";
  24 }
  25 ```
  26 [Try this example on Compiler Explorer.](https://godbolt.org/z/13xo1P5oz)
  27
  28 The internalized records are passed on to various backends, which extract
  29 information from a subset of the records and generate one or more output files.
  30
  31 These output files are typically .inc files for C++, but may be any type of file
  32 that the backend developer needs.
  33
  34 Resources for learning the language:
  35 * [TableGen Overview](https://llvm.org/docs/TableGen/index.html)
  36 * [Programmer's reference guide](https://llvm.org/docs/TableGen/ProgRef.html)
  37 * [Tutorial](jupyter/tablegen_tutorial_part_1.ipynb)
  38 * [Tools for Learning LLVM TableGen](https://blog.llvm.org/posts/2023-12-07-tools-for-learning-llvm-tablegen/)
  39 * [Lessons in TableGen](https://www.youtube.com/watch?v=45gmF77JFBY) (video),
  40   [slides](https://archive.fosdem.org/2019/schedule/event/llvm_tablegen/attachments/slides/3304/export/events/attachments/llvm_tablegen/slides/3304/tablegen.pdf)
  41 * [Improving Your TableGen Descriptions](https://www.youtube.com/watch?v=dIEVUlsiktQ)
  42   (video), [slides](https://llvm.org/devmtg/2019-10/slides/Absar-ImprovingYourTableGenDescription.pdf)
  43
  44 Writing TableGen backends:
  45 * [TableGen Backend Developer's Guide](https://llvm.org/docs/TableGen/BackGuide.html)
  46 * [How to write a TableGen backend](https://www.youtube.com/watch?v=UP-LBRbvI_U)
  47   (video), [slides](https://llvm.org/devmtg/2021-11/slides/2021-how-to-write-a-tablegen-backend.pdf), also available as a
  48         [notebook](jupyter/sql_query_backend.ipynb).
  49
  50 TableGen in MLIR:
  51 * [Operation Definition Specification](https://mlir.llvm.org/docs/DefiningDialects/Operations/)
  52 * [Defining Dialect Attributes and Types](https://mlir.llvm.org/docs/DefiningDialects/AttributesAndTypes/)
  53
  54 Useful tools:
  55 * [TableGen Jupyter Kernel](jupyter/)
  56 * [TableGen LSP Language Server](https://mlir.llvm.org/docs/Tools/MLIRLSP/#tablegen-lsp-language-server--tblgen-lsp-server)
  57