Frequently Asked Questions (FAQ)
- How do I install clangd?
- How do I check the clangd version I am using?
- Can you give an example configuration file for clangd?
- How do I build clangd from sources?
- How do I stop clangd from indexing certain folders?
- How do I make additional headers visible to clangd?
- Why does clangd not return all references for a symbol?
- How do I fix errors I get when opening headers outside of my project directory?
- What can I do if clangd chooses the wrong source file to infer commands for a header?
- Why does clangd produce false or missing diagnostics?
- Does clangd support CUDA?
- Error “Unable to handle compilation, expected exactly one compiler job” (macOS)
- How can I detect clangd in the preprocessor?
How do I install clangd?
Clangd is often distributed either within LLVM packages or in a separate Clang-related packages (e.g. clang-tools on Ubuntu). These packages (mostly) follow official LLVM releases, which are released once every 6 months.
If you want to use new versions of clangd, you have several options:
- Download the binaries from our GitHub repository:
- Compile from sources.
How do I check the clangd version I am using?
- Check the logs: clangd prints version on the first line. See your LSP client
documentation on where to find them: e.g. VSCode has logs in the output panel,
coc-clangd gives you the logs via
clangd --version. Note: the binary in your
$PATHmight not be the one used within the editor, checking logs is preferred.
Can you give an example configuration file for clangd?
The preferred way to store clangd configuration is through YAML files. Here’s an example config you could use:
CompileFlags: # Treat code as C++, use C++17 standard, enable more warnings. Add: [-xc++, -std=c++17, -Wall, -Wno-missing-prototypes] # Remove extra warnings specified in compile commands. # Single value is also acceptable, same as "Remove: [-mabi]" Remove: -mabi Diagnostics: # Tweak Clang-Tidy checks. ClangTidy: Add: [performance*, modernize*, readability*] Remove: [modernize-use-trailing-return-type] CheckOptions: readability-identifier-naming.VariableCase: CamelCase --- # Use Remote Index Service for LLVM. If: # Note: This is a regexp, notice '.*' at the end of PathMatch string. PathMatch: /path/to/llvm/.* Index: External: Server: clangd-index.llvm.org:5900 MountPoint: /path/to/llvm/
This can go in your project as
.clangd or a global
How do I build clangd from sources?
If you are a developer or downloading pre-built binaries is not an option, you
instructions and make sure
How do I stop clangd from indexing certain folders?
If: # Note: This is a regexp, notice '.*' at the end of PathMatch string. PathMatch: /my/project/large/dir/.* Index: # Disable slow background indexing of these files. Background: Skip
How do I make additional headers visible to clangd?
If you have some headers outside of the visibility of clangd, you can either
include individual headers (
-include=/headers/file.h) or add
directories to the include path (
-I=/other/headers). The easiest way to do
that is through configuration file:
CompileFlags: Add: [-include=/headers/file.h, -I=/other/headers]
Why does clangd not return all references for a symbol?
One of the potential reasons is that clangd has not indexed all the files in
your project. Please make sure all files are visible to clangd through the
project setup and
If you are sure all files are indexed and can be accessed: clangd limits the
number of returned results to prevent UI freezes by default. If you have more
than a 1000 symbols and you would like to get through all of them, please pass
--limit-references=0 to clangd invocation.
The same applies to the Remote Index Service but we are not respecting
--limit-references=0 on the server side to prevent DDoS attacks.
How do I fix errors I get when opening headers outside of my project directory?
Clangd might fail to find suitable compile flags for headers outside of your project directory (e.g. third party dependencies installed elsewhere – for more details see here).
To work around this, you can instruct clangd to use your project’s compilation database for all files, not just files in the project directory.
This can be done by passing the path of the directory containing the compilation
datbase as a
--compile-commands-dir=<path> command-line argument to clangd.
What can I do if clangd chooses the wrong source file to infer commands for a header?
A tool like
can be used to post-process a
compile_commands.json file to also contain
entries for headers.
In the absence of entries for headers, clangd will use heuristics to choose a source file whose compile command to use when opening a header. The heuristics are currently based on filesystem paths and can sometimes choose the wrong source file, though improvements are planned.
Why does clangd produce false or missing diagnostics?
To provide increased responsiveness, clangd skips parsing the bodies of functions defined in included headers. This optimization can result in:
False positive diagnotics, particularly around unused declarations (if the relevant uses are in the code that was skipped). This can be worked around by suppressing affected diagnostic categories in the config file.
Missing diagnostics, if they occur in code that was skipped. See this issue for some discussion.
If you believe a false or missing diagnostic is not related to this (and also not configuration-related, i.e. resulting from clang using the wrong compile command for a file), please file a bug in the issue tracker.
Does clangd support CUDA?
There is some support, but it’s not very polished or tested. clangd uses clang to parse code and clang can understand CUDA code.
Generally you’ll need to:
- ensure that your editor plugin is enabling clangd when CUDA files are open (e.g. enabling for extension
- make sure that clangd understands these are CUDA files (e.g. by extension
*.cuor adding the clang flag
- set the path to your cuda installation if it isn’t detected, by adding the clang flag
Error “Unable to handle compilation, expected exactly one compiler job” (macOS)
If your project is configured to build for both ARM (M1) and Intel (x64), you’ll see this error on clangd <= 13.
is that the flags
arch x86_64 -arch arm64 tell clang to parse the code twice in
different configurations, and we’re not sure which to use. (clangd 14 will pick the first one).
You can work around the problem by tweaking the compile flags in your clangd config file:
CompileFlags: Remove: [-arch] Add: [-arch, x86_64]
(In other cases, this error message indicates a compile command we don’t understand. If you’re not on a Mac it’s more likely your compile flags are badly malformed.)
How can I detect clangd in the preprocessor?
clangd uses the clang parser, and defines preprocessor symbols like
Code that detects compilers will detect it as clang, which is usually good.
If a library can’t be parsed by clang, it generally can’t be parsed by clangd either.
Clangd does not define any extra symbols allowing you to detect it specifically.
But you must write
#ifdef _CLANGD, you can configure this:
CompileFlags: Add: [-D_CLANGD=1]