A project-wide index can be slow to build, particlarly 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 your 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 symbols that can be exported from headers (functions,
classes, types, etc).
It’s usually 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 official LLVM releases do not yet include remote index support, but unofficial weekly snapshots are available for common platforms.
You can also build from source. This requires more effort and time, so is mostly useful if you are interested in modifying or debugging the source code.
Downloading latest release from GitHub
Weekly snapshots of clangd are available on GitHub clangd/clangd releases. These binaries are built with remote index support.
NOTE: Snapshots are marked as “pre-release” so the “latest release” points to the latest major LLVM release (e.g. 11.0.0). Remote index is not enabled in the major releases yet.
Building from sources
In general you can follow the LLVM instructions
llvm-project with CMake. You’ll need the following CMake flags:
-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra(to build clangd)
-DCLANGD_ENABLE_REMOTE=On(remote index is off by default)
Remote index implementation depends on gRPC and Protobuf libraries. You’ll
need to provide these dependencies either via compiling gRPC from
sources or system
apt install libgrpc++-dev libprotobuf-dev
protobuf-compiler-grpc in Ubuntu and Debian,
brew install grpc protobuf on
macOS). If your installation cannot be discovered by CMake automatically or
you want to use a custom installation, you can use
tell CMake about a particular directory.
Once you have cmake set up, you can build the
clangd target, and optionally
Using remote index feature
When using clangd with remote index support, you can specify the server to connect to in two ways:
- clangd configuration files (recommended)
- clangd flags
--project-root(best for testing)
Either way, you’ll need to specify a server address such as
and the project root on your local machine, e.g.
The project root is used to translate paths from the server to your machine.
An unofficial test service is available for LLVM. The configuration scripts for this service may be a useful starting point if you want to host an index.