Remote index

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.

Indexer

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, to produce compile_commands.json and possibly generate source files.

Running clangd-indexer is expensive and produced index is not incremental. Usually the index is produced periodically and so is always slightly stale.

Server

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. The --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.

clangd client

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 to build 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 libraries (e.g. 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 -DGRPC_INSTALL_PATH to tell CMake about a particular directory.

Once you have cmake set up, you can build the clangd target, and optionally clangd-index-server and clangd-indexer.

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 --remote-index-address and --project-root (best for testing)

Either way, you’ll need to specify a server address such as 127.0.0.1:50051, and the project root on your local machine, e.g. /home/me/src/my-project/. 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.