[PATCH] D137770: [docs] Introduce clangd part in StandardCPlusPlusModules

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu created this revision.
ChuanqiXu added reviewers: sammccall, nridge.
Herald added subscribers: kadircet, arphaman.
Herald added a project: All.
ChuanqiXu requested review of this revision.
Herald added subscribers: cfe-commits, MaskRay, ilya-biryukov.
Herald added a project: clang.

Introduce clangd part in to the document to tell end users about the status quo. It is pretty important since nowadays it is painful to write codes without the help form the code intelligence.

And my feeling in the recent days is that: the current status is obviously very far from good but it is not useless completely.  As long as we can get a `compile_commands.json`, the clangd can start to work in some degree. And it should be easy for the build systems to generate the `compile_commands.json`. So I think it is meaningful to document the status quo.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D137770

Files:
  clang/docs/StandardCPlusPlusModules.rst


Index: clang/docs/StandardCPlusPlusModules.rst
===================================================================
--- clang/docs/StandardCPlusPlusModules.rst
+++ clang/docs/StandardCPlusPlusModules.rst
@@ -821,6 +821,63 @@
 there are some differences between header units and Clang modules and that ignoring those
 differences now would likely become a problem in the future.
 
+Interoperability with tool chains
+=================================
+
+The modules change the traditional header based C++ project structures drastically.
+So the interoperability of many tool chains is broken. Here we track the status quo
+and the interoperability with clang for different tools.
+
+clangd
+======
+
+The clangd is a language server that can work with many editors via a plugin.
+The clangd can show diagnostics of errors and warnings in-place, suggest fixes,
+show extra hints about code problems and suggest code completion.
+
+Since clangd will invoke clang to parse the files according to flags from the
+`compilation database <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_,
+so as long as the clang can compile the files by these flags in the compilation database,
+the clangd should be able to handle the files in some level.
+
+So given clang can compile some modules codes now,
+the clangd can work for modules in some degree. The following is an simple example to show
+how to use clangd for modules:
+
+.. code-block:: c++
+
+  // A.cppm
+  export module A;
+  export void printA() {}
+
+  // Use.cpp
+  import A;
+  void foo() {
+  }
+
+  // compile_commands.json
+  [
+    {
+      "directory": "DIR",
+      "command": "clang++  -fprebuilt-module-path=DIR -std=c++20 -o DIR/main.cpp.o -c DIR/Use.cpp",
+      "file": "DIR/Use.cpp"
+    }
+  ]
+
+Now the important part is that we need to compile module A to BMI first:
+
+.. code-block:: console
+  
+  clang++  -fprebuilt-module-path=DIR -std=c++20 -o DIR/main.cpp.o -c DIR/Use.cpp
+
+Then in ``Use.cpp``, when we type `pr`, we can find the suggestion to `printA`.
+And if we require to find the definition for `printA`, we can go to the definition corretly.
+
+However, since modules bring completely new relationship to the C++ projects and
+clangd doesn't do special corresponding changes. It is natural that the interactions
+are not friendly, there are a lot of defects and even crashes. We can track the newest status
+in https://github.com/clangd/clangd/issues/1293.
+
 Possible Questions
 ==================
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D137770.474474.patch
Type: text/x-patch
Size: 2495 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20221110/75ce0b9e/attachment.bin>