A project-wide index can be slow to build, particularly for large projects on slower machines like laptops. A “remote index” allows a shared server to host the index instead.
How it works
The remote index has three components:
- the indexer is a batch process that should run on a powerful machine. It parses all the code for your project, and produces an index file.
- the server exposes the index over a network. It loads the index file into memory, and exposes a gRPC service to query it.
- the client is part of clangd, which runs on the development machine. It connects to the server and requests information (such as the definition of a symbol) in real-time.
Each of these components are open-source and part of llvm/llvm-project/clang-tools-extra/clangd.
clangd-indexer collects public symbols from headers (functions, classes,
types, etc). It’s necessary to run the build system for your project first,
compile_commands.json and possibly generate source files.
clangd-indexer is expensive and produced index is not incremental.
Usually the index is produced periodically and so is always slightly stale.
clangd-index-server is an RPC server that processes index requests. Clangd
issues requests to the server whenever it uses its global index (e.g. find
references request, index-based code completion).
The source code lives under different paths on different machines.
--project-root flags specifies the source root on the indexer machine,
this prefix will be stripped. The client will add its own prefix as appropriate.
The client is compiled into clangd, and enabled when
set in the user config. A “mount point” must also be specified to
translate between local and remote paths.
The remote index cannot be enabled from project config for privacy reasons (the client reveals information about the code being edited, and the project config from the source code repository isn’t sufficiently trusted).
The client and server require the gRPC libraries. Because of this dependency, they are not enabled by default in CMake.
To build remote-index-enabled
clangd-index-server, you need:
- gRPC libraries (e.g.
apt install libgrpc++-dev libprotobuf-dev protobuf-compiler-grpcor
brew install grpc protobufor build from source)
- to set the
The clangd releases on GitHub include remote index support, but official LLVM releases do not (yet).