Design of clangd

A language server’s main responsibilities are:

Most of the design documentation focuses on the concepts, if you’re interested in the implementation we try to keep the code well-documented.

code walkthrough

Request handling

clangd is based on the clang compiler, and at its core runs the clang parser in a loop. The parser produces diagnostics as it encounters problems, and the end result is a clang AST. The AST is saved to answer queries like “what kind of symbol is under the cursor”.

There is one such loop for each open file. The TUScheduler class manages a collection of ASTWorkers, each running on its own thread. Most operations run on these threads, though code completion is a notable exception.

threads and request handling


C/C++/Objective-C are designed so that you can parse one source file at a time, without needing to see the whole program. This means that the resulting AST lacks certain information:

To solve this, clangd maintains a database of symbols found anywhere in the program, called the index. This is extracted from each open file as it is parsed, and also by parsing the whole project in the background.

the clangd index

Remote index

The remote index system allows a codebase index to be built offline and shared across many clangd instances with an RPC server.

remote index