clangd

Usage / 使用方式

English

This build adds generated compile database support for C++ modules on top of the regular clangd extension.

How to use

1. Use the latest available clangd when possible. Tested with clangd 22.1.0 and newer.
2. If you are not using CMake, set clangd.modules.fallbackBuildDirectory to the directory that contains compile_commands.json.
3. To regenerate manually, run clangd: Refresh Generated Compile Commands from the command palette.

Details

• The generated database supports GCC, MSVC, and Clang. The extension invokes the matching compiler dependency scanner to determine C++ module dependencies.
• If you use CMake Tools, keep cmake.exportCompileCommandsFile set to true so CMake exports the compilation database. This setting defaults to true.
• If the CMake Tools extension is available, this extension follows the active CMake project and reads its compile_commands.json.
• If CMake Tools is not available, it falls back to clangd.modules.fallbackBuildDirectory, which defaults to build under the active workspace folder.
• The extension writes a generated clangd database to <build-dir>/.clangd/compile_commands.json and starts clangd with --compile-commands-dir=<build-dir>/.clangd and --experimental-modules-support.

Useful settings:

{
  "clangd.modules.enabled": true,
  "clangd.modules.fallbackBuildDirectory": "build"
}

中文

这个版本在常规 clangd 扩展基础上，增加了用于 C++ modules 的生成式编译数据库支持。

使用方式

1. 推荐尽量使用最新版本 clangd。已使用 clangd 22.1.0 及更新版本测试。
2. 如果不使用 CMake，请将 clangd.modules.fallbackBuildDirectory 指向包含 compile_commands.json 的目录。
3. 如需手动重新生成，可在命令面板运行 clangd: Refresh Generated Compile Commands。

细节

• 生成式编译数据库支持 GCC、MSVC 和 Clang。扩展会调用对应编译器的依赖扫描能力来确定 C++ module 依赖关系。
• 如果使用 CMake Tools，请保持 cmake.exportCompileCommandsFile 为 true，让 CMake 导出编译数据库。该配置默认值就是 true。
• 如果 CMake Tools 扩展可用，本扩展会跟随当前 active CMake project，并读取对应的 compile_commands.json。
• 如果 CMake Tools 不可用，则使用 clangd.modules.fallbackBuildDirectory，默认是当前 workspace 下的 build 目录。
• 扩展会把生成后的 clangd 编译数据库写入 <build-dir>/.clangd/compile_commands.json，并使用 --compile-commands-dir=<build-dir>/.clangd 和 --experimental-modules-support 启动 clangd。

常用配置：

{
  "clangd.modules.enabled": true,
  "clangd.modules.fallbackBuildDirectory": "build"
}

clangd helps developers write, understand and improve C/C++ code by providing:

• code completion
• compile errors and warnings
• go-to-definition and cross references
• hover information and inlay hints
• include management
• code formatting
• simple refactorings

Full documentation for clangd is at clangd.llvm.org.

Setup

clangd server

The extension requires the clangd language server. You will be prompted to download it if it's not found on your PATH. (Automatic installation is possible on x86-64 Linux, Windows, and Mac).

If you have an old version of clangd installed on your system already, you can run "Check for clangd language server update" from the command palette.

Project setup

clangd is based on the clang C++ compiler, and understands even complex C++ code. However, you must tell clangd how your project is built (compile flags). A compile_commands.json file can usually be generated by your build system (e.g. with CMake, by setting -DCMAKE_EXPORT_COMPILE_COMMANDS=1).

See Project Setup in the clangd documentation for details and alternatives.

The clangd server also supports a number of feature customizations using its config file.

Features

Code completion

Suggestions will appear as you type names, or after . or ->. Because clangd uses a full C++ parser, code completion has access to precise type information.

Errors, warnings, and clang-tidy

Code errors are shown as you type (both as red squiggle underlines, and in the "Problems" panel). These are the same as produced by the clang compiler, and suggested fixes can automatically be applied.

Most clang-tidy checks are supported (these can be enabled using a .clang-tidy file).

Cross-references

Go-to-definition and find-references work across your code, using a project-wide index.

Press Ctrl-P # to quickly navigate to a symbol by name.

Hover and inlay hints

Clangd can describe almost any entity if you hover the mouse (or press Ctrl-KI).

Inlay hints for parameters and deduced types can be shown temporarily or permanently (the editor.inlayHints.enabled setting controls this).

Include management

Code completion works across your codebase and adds #include directives where needed. The • shows includes that will be inserted.

clangd can suggest inserting missing #includes, where they cause errors. It can warn on unused includes.

Formatting

clangd uses the clang-format engine. You can format a file or the selection. When "Format on Type" is enabled in the settings, pressing enter will cause clangd to format the old line and semantically reindent.

The style used for formatting (and certain other operations) is controlled by the project's .clang-format file.

Note that if you prefer to use something other than clangd for formatting, you can choose a different formatter with the "editor.defaultFormatter" setting.

Refactoring

clangd supports some local refactorings. When you select an expression or declaration, the lightbulb menu appears and you can choose a code action.

Current refactorings include:

• extract variable/function
• expand auto types and macros
• use raw strings
• rename (bound to <F2>, rather than a contextual code action)

Bugs/contributing

clangd is part of the LLVM project.

If you'd like to help out, reach out to clangd-dev@lists.llvm.org.

If you've found a bug in this extension, please file it at https://github.com/clangd/vscode-clangd/issues. If you've found a bug in clangd, please file at https://github.com/clangd/clangd/issues.