iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
🐷

A Guide to clangd Configuration Files

に公開
Vim
lsp
clangd
tech

I am documenting my setup for vim-lsp and clangd as I found it a bit complicated.

Environment

  • Vim 9.1
  • vim-lsp
  • vim-lsp-settings
  • Ubuntu 22.04
  • gcc 11.4.0
  • clangd 14.0.0

Motivation

When I wanted to write C/C++, I had a strong desire to properly configure include paths and other settings with vim-lsp. During coding, I was encountering the following issues:

  • Standard library not being autocompleted
  • Warnings appearing for standard library include paths
  • std namespace could not be resolved
  • Unable to resolve headers within the project

In short, I was frustrated by the constant stream of warnings.
↓ It looked like this: SO ANNOYING!
Motivation

Although I am using Vim for code and configuration examples, they can be applied in the same way in VS Code.

For those who just want the conclusion

If you just want it to work immediately, save the following YAML as .clangd in your project root.
Note that this is specific to Ubuntu.

.clangd
If:
    PathMatch: .*

CompileFlags:
    Add:
        - -Wall
        - -xc++
        - -std=c++17
        - --target=x86_64-linux-gnu
        - --include-directory=/usr/include/c++/11
        - --include-directory=/usr/include/x86_64-linux-gnu/c++/11
    Compiler: g++

Please adjust the --target and --include-directory settings to match your specific environment.
Specifically, --include-directory paths can be found by running g++ with the -v (verbose) option.

Preparing vim-lsp and clangd

This assumes you are using vim-lsp-settings.
Add the following to your .vimrc to include the --enable-config option when clangd starts. By adding this option, you will be able to load the .clangd configuration file mentioned below.

.vimrc
let g:lsp_settings = {
            \ 'clangd': {
            \   'cmd': ['clangd', '--enable-config'],
            \ }
            \}

clangd configuration files (.clangd, config.yaml)

clangd reads the following two configuration files. Changes are reflected even while clangd is running.

  • User configuration: config.yaml

    • Windows: %LocalAppData%\clangd\config.yaml
    • macOS: ~/Library/Preferences/clangd/config.yaml
    • Linux and others: $XDG_CONFIG_HOME/clangd/config.yaml

  • Project configuration: .clangd
    Place this in the project root.

Both config.yaml and .clangd are defined as YAML files.

clangd configuration content

Please try it out yourself while experimenting with .clangd.

If

  • PathMatch
  • PathExclude
If:
    PathMatch:
    PathExclude:

CompileFlags

CompileFlags:
    Add:
    Remove:
    Compiler:

Index

These are settings for the project index.
Configuring these properly will speed up and improve the accuracy of autocompletion, jump-to-definition, etc.

Background

Index:
    Background:

External

Index:
    External:

StandardLibrary

Index:
    StandardLibrary:

Style

Style:
    FullyQualifiedNamespaces:

Diagnostics

Completion

InlayHints

These are settings for InlayHints. The following image should explain it better than text.

InlayHints

It displays Virtual Text for features like visualizing designators, showing types for variables declared with auto, and displaying function parameter names.
I personally set only Designators to No, as shown below.

InlayHints:
    Enabled: Yes        # InlayHints switch
    Designators: No     # Show designators
    DeducedTypes: Yes   # Show deduced types
    ParameterNames: Yes # Show parameter names
    BlockEnd: Yes       # Show block ends
    TypeNameLimit: 24   # Limit for type name length

Hover

Provides switches for information displayed via Hover.
Currently, it seems limited to ShowAKA. ShowAKA (AKA: Also Known As) displays the original type name for user-defined types, etc.

Hover:
    ShowAKA: Yes

For example, in the following case, I set a type alias as using VecI = vector<int>;.
vim-lsp's LspHover will display the original type name for variables declared with the type alias.

Hover

Semantic Tokens

Configuration Example

I feel there are no major inconveniences with just this setup. I keep this configuration in my config.yaml.

  • Autocompletion for standard library includes works
  • Autocompletion for project header includes works
  • All standard warnings are reported
  • InlayHints enabled
If:
    PathMatch: .*

CompileFlags:
    Add:
        - -Wall
        - -xc++
        - -std=c++17
        - --target=x86_64-linux-gnu
        - --include-directory=/usr/include/c++/11
        - --include-directory=/usr/include/x86_64-linux-gnu/c++/11
    Compiler: g++
GitHubで編集を提案

Discussion