Getting started

To use clangd, you need:

Installing clangd

For best results, use the most recent version of clangd.

You can check the version currently installed with clangd --version.

(Version numbers are based on LLVM. clangd 7 was the first usable release).

Installing with a package manager

Mac OS X

Clangd can be installed (along with LLVM) via Homebrew:

brew install llvm

or with MacPorts:

sudo port install clang-11
Windows

Download the LLVM installer from releases.llvm.org

Debian/Ubuntu

Installing the clangd package will usually give you a slightly older version.

Try to install a packaged release (12.0):

sudo apt-get install clangd-12

If that’s not found, at least clangd-9 or clangd-8 should be available. Versions before 8 were part of the clang-tools package.

This will install clangd as /usr/bin/clangd-12. Make it the default clangd:

sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-12 100
Other systems

Most distributions include clangd in a clangd package, in a clang-tools package, or in the full llvm distribution.

For some platforms, binaries are also available at releases.llvm.org.

Standalone .zip releases

You can also download binaries directly for macOS, windows, and Linux (x86-64): latest stable release.

If you live on the bleeding edge, snapshot pre-releases are built weekly and available on the github releases page.

Compiling from sources

You can find instructions in llvm-project.

Editor plugins

Language Server plugins are available for many editors. In principle clangd should work with any of them, though feature set and interface may vary.

Here are some plugins we know work well with clangd:

Vim

YouCompleteMe can be installed with clangd support. This is not on by default, you must install it with install.py --clangd-completer.

We recommend changing a couple of YCM’s default settings. In .vimrc add:

" Let clangd fully control code completion
let g:ycm_clangd_uses_ycmd_caching = 0
" Use installed clangd, not YCM-bundled clangd which doesn't get updates.
let g:ycm_clangd_binary_path = exepath("clangd")

You should see errors highlighted and completions as you type.

Code completion in YouCompleteMe

YouCompleteMe supports many of clangd’s features:

Under the hood


LanguageClient-neovim also has instructions for using clangd, and may be easier to install.

Emacs

eglot can be configured to work with clangd.

Install eglot with M-x package-install RET eglot RET.

Add the following to ~/.emacs to enable clangd:

(require 'eglot)
(add-to-list 'eglot-server-programs '((c++-mode c-mode) "clangd"))
(add-hook 'c-mode-hook 'eglot-ensure)
(add-hook 'c++-mode-hook 'eglot-ensure)

After restarting you should see diagnostics for errors in your code, and M-x completion-at-point should work.

Diagnostics in Emacs

eglot supports many of clangd’s features, with caveats:

company-mode

eglot does have basic integration with company-mode, which provides a more fluent completion UI.

You can install it with M-x package-install RET company RET, and enable it with M-x company-mode.

Completion in company-mode

Under the hood

Visual Studio Code

The official extension is vscode-clangd and can be installed from within VSCode.

Choose View –> Extensions, then search for “clangd”. (Make sure the Microsoft C/C++ extension is not installed).

After restarting, you should see red underlines underneath errors, and you should get rich code completions including e.g. function parameters.

Code completion in VSCode

vscode-clangd has excellent support for all clangd features, including:

Under the hood

Sublime Text

tomv564/LSP works with clangd out of the box.

Select Tools–>Install Package Control (if you haven’t installed it yet).

Press Ctrl-Shift-P and select Package Control: Install Package. Select LSP.

Press Ctrl-Shift-P and select LSP: Enable Language Server Globally. Select clangd.

Open a C++ file, and you should see diagnostics and completion:

Completion in Sublime Text

The LSP package has excellent support for all most clangd features, including:

Under the hood

Settings can be tweaked under Preferences–>Package Settings–>LSP.

Other editors

There is a directory of LSP clients at langserver.org.

A generic client should be configured to run the command clangd, and communicate via the language server protocol on standard input/output.

If you don’t have strong feelings about an editor, we suggest you try out VSCode, it has excellent language server support and most faithfully demonstrates what clangd can do.

Project setup

To understand your source code, clangd needs to know your build flags. (This is just a fact of life in C++, source files are not self-contained).

By default, clangd will assume your code is built as clang some_file.cc, and you’ll probably get spurious errors about missing #included files, etc. There are a couple of ways to fix this.

compile_commands.json

This file provides compile commands for every source file in a project. It is usually generated by tools.

clangd will look in the parent directories of the files you edit looking for it, and also in subdirectories named build/. For example, if editing $SRC/gui/window.cpp, we search in $SRC/gui/, $SRC/gui/build/, $SRC/, $SRC/build/, …

CMake-based projects

If your project builds with CMake, it can generate this file. You should enable it with:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1

compile_commands.json will be written to your build directory. If your build directory is $SRC or $SRC/build, clangd will find it. Otherwise, symlink or copy it to $SRC, the root of your source tree.

ln -s ~/myproject-build/compile_commands.json ~/myproject/
Bazel-based projects

Bazel can generate this file via this extractor extension. Refer to instructions in the project README; it is intended for use with clangd.

Other build systems, using Bear

Bear is a tool to generate a compile_commands.json file by recording a complete build.

For a make-based build, you can run make clean; bear -- make to generate the file (and run a clean build!).

Other tools can also generate this file. See the compile_commands.json specification.

compile_flags.txt

If all files in a project use the same build flags, you can put those flags one-per-line in compile_flags.txt in your source root.

Clangd will assume the compile command is clang $FLAGS some_file.cc.

Creating this file by hand is a reasonable place to start if your project is quite simple. However background-indexing will not work, as clangd can’t be sure which of the files are project sources.

This file will be ignored if compile_commands.json is present.

✏️