[Mlir-commits] [mlir] 1b501cb - [mlir] Add documentation for TableGen LSP features and setup
River Riddle
llvmlistbot at llvm.org
Mon Jun 6 18:29:50 PDT 2022
Author: River Riddle
Date: 2022-06-06T18:29:31-07:00
New Revision: 1b501cbcbb275c48b23f164bb75f592ed1c2a883
URL: https://github.com/llvm/llvm-project/commit/1b501cbcbb275c48b23f164bb75f592ed1c2a883
DIFF: https://github.com/llvm/llvm-project/commit/1b501cbcbb275c48b23f164bb75f592ed1c2a883.diff
LOG: [mlir] Add documentation for TableGen LSP features and setup
This commit beefs up the documentation for MLIR language servers by
adding proper documentations/examples/etc for the provided TableGen
language server capabilities. Given that this documentation is also used
for the vscode extension, this commit also updates the user facing vscode
extension documentation.
Note that the images referenced in the new documentation are hosted on
the website, and will be commited to mlir-www shortly after this commit
lands.
Added:
Modified:
mlir/docs/Tools/MLIRLSP.md
Removed:
################################################################################
diff --git a/mlir/docs/Tools/MLIRLSP.md b/mlir/docs/Tools/MLIRLSP.md
index 41c0b20db7736..baadf42c98ed2 100644
--- a/mlir/docs/Tools/MLIRLSP.md
+++ b/mlir/docs/Tools/MLIRLSP.md
@@ -219,6 +219,77 @@ necessarily provided by all IDE clients.
+## TableGen LSP Language Server : `tblgen-lsp-server`
+
+MLIR provides an implementation of an LSP language server for `.td` text files
+in the form of the `tblgen-lsp-server` tool. This tool interacts with the
+TableGen C++ API to support rich language queries, such as "Find Definition".
+
+### Compilation Database
+
+Similarly to
+[`clangd`](https://clang.llvm.org/docs/JSONCompilationDatabase.html), and
+language servers for various other programming languages, the TableGen language
+server relies on a compilation database to provide build-system information for
+`.td` files. This information includes, for example, the include directories
+available for that file. This database allows for the server to interact with
+`.td` files using the same configuration as when building.
+
+#### Format
+
+A TableGen compilation database is a YAML file, conventionally named
+`tablegen_compile_commands.yml`, that contains a set of `FileInfo` documents
+providing information for individiual `.td` files.
+
+Example:
+
+```yaml
+--- !FileInfo:
+ filepath: "/home/user/llvm/mlir/lib/Dialect/Arithmetic/IR/ArithmeticCanonicalization.td"
+ includes: "/home/user/llvm/mlir/lib/Dialect/Arithmetic/IR;/home/user/llvm/mlir/include"
+```
+
+- filepath: <string> - Absolute file path of the file.
+- includes: <string> - Semi-colon delimited list of absolute include directories.
+
+#### Build System Integration
+
+Per convention, TableGen compilation databases should be named
+`tablegen_compile_commands.yml` and placed at the top of the build directory.
+When using CMake and `mlir_tablegen`, a compilation database is generally
+automatically built and placed in the appropriate location.
+
+### Features
+
+This section details a few of the features that the TableGen language server
+provides. The screenshots are shown in [VSCode](https://code.visualstudio.com/),
+but the exact feature set available will depend on your editor client.
+
+[tablegen features]: #
+
+#### Diagnostics
+
+The language server actively runs verification as you type, showing any
+generated diagnostics in-place.
+
+
+
+#### Cross-references
+
+Cross references allow for navigating the code base.
+
+##### Find definition
+
+Jump to the definition of a symbol under the cursor:
+
+
+
+##### Find references
+
+Show all references of the symbol under the cursor.
+
+
+
## Language Server Design
The design of the various language servers provided by MLIR are effectively the
@@ -271,8 +342,8 @@ to work:
### Visual Studio Code
Provides language IDE features for [MLIR](https://mlir.llvm.org/) related
-languages: [MLIR](#mlir---mlir-textual-assembly-format) and
-[PDLL](#pdll---mlir-pdll-pattern-files)
+languages: [MLIR](#mlir---mlir-textual-assembly-format),
+[PDLL](#pdll---mlir-pdll-pattern-files), and [TableGen](#td---tablegen-files)
#### `.mlir` - MLIR textual assembly format:
@@ -336,6 +407,40 @@ available in or a unique location, additional `pdll_compile_commands.yml` files
may be specified via the `mlir.pdll_compilation_databases` setting. The paths of
these databases may be absolute or relative within your workspace.
+#### `.td` - TableGen files:
+
+The MLIR extension adds language support for the
+[TableGen language](https://llvm.org/docs/TableGen/ProgRef.html).
+
+##### Features
+
+- Syntax highlighting for `.td` files and `tablegen` markdown blocks
+- go-to-definition and cross references
+
+[tablegen-vscode features]: #
+
+##### Setup
+
+###### `tblgen-lsp-server`
+
+The various `.td` language features require the
+[`tblgen-lsp-server` language server](https://mlir.llvm.org/docs/Tools/MLIRLSP/#tablegen-lsp-language-server--tblgen-lsp-server).
+If `tblgen-lsp-server` is not found within your workspace path, you must specify
+the path of the server via the `mlir.tablegen_server_path` setting. The path of
+the server may be absolute or relative within your workspace.
+
+###### Project setup
+
+To properly understand and interact with `.td` files, the language server must
+understand how the project is built (compile flags).
+[`tablegen_compile_commands.yml` files](https://mlir.llvm.org/docs/Tools/MLIRLSP/#compilation-database-1)
+related to your project should be provided to ensure files are properly
+processed. These files can usually be generated by the build system, and the
+server will attempt to find them within your `build/` directory. If not
+available in or a unique location, additional `tablegen_compile_commands.yml`
+files may be specified via the `mlir.tablegen_compilation_databases` setting.
+The paths of these databases may be absolute or relative within your workspace.
+
#### Contributing
This extension is actively developed within the
More information about the Mlir-commits
mailing list