Configuration

The configuration mechanism is new in clangd 11, and more options will be exposed in this way in future.

Contents

Files

Configuration is stored in YAML files. These are either:

Each file can contain multiple fragments separated by --- lines. (This is only useful if the fragments have different If conditions).

JSON is a subset of YAML, so you can use that syntax if you prefer.

Changes should take effect immediately as you continue to edit code.

Loading and combining fragments

By default, user configuration applies to all files that are opened. Project configuration applies to files under its tree (proj/.clangd configures proj/**).

If conditions can further limit this, e.g. to configure only header files.

Configuration is combined when this is sensible. In case of conflicts, user config has the highest precedence, then inner project, then outer project.

Schema

At the top-level, a fragment is a key-value mapping that divides the document into “blocks” of related options, each of which is a key-value mapping.

In most places where an array of scalar values can be specified, a single value is also acceptable. e.g. Add: -Wall is equivalent to Add: [-Wall].

If

Conditions in the If block restrict when a fragment applies.

If:                               # Apply this config conditionally
  PathMatch: .*\.h                # to all headers...
  PathExclude: include/llvm-c/.*  # except those under include/llvm-c/

Each separate condition must match (combined with AND). When one condition has multiple values, any may match (combined with OR). e.g. PathMatch: [foo/.*, bar/.*] matches files in either directory.

Conditions based on a file’s path use the following form:

If no file is being processed, these conditions will not match.

PathMatch

The file being processed must fully match a regular expression.

PathExclude

The file being processed must not fully match a regular expression.

CompileFlags

Affects how a source file is parsed.

CompileFlags:                     # Tweak the parse settings
  Add: [-xc++, -Wall]             # treat all files as C++, enable more warnings
  Remove: [-W*]                     # strip all other warning-related flags
  Compiler: clang++               # Change argv[0] of compile flags to `clang++`

clangd emulates how clang would interpret a file. By default, it behaves roughly as clang $FILENAME, but real projects usually require setting the include path (with the -I flag), defining preprocessor symbols, configuring warnings etc.

Often, a compilation database specifies these compile commands. clangd searches for compile_commands.json in parents of the source file.

This section modifies how the compile command is constructed.

Add

List of flags to append to the compile command.

Remove

List of flags to remove from the compile command.

In all cases, -Xclang is also removed where needed.

Example:

Flags added by the same CompileFlags entry will not be removed.

CompilationDatabase

Directory to search for compilation database (compile_commands.json etc). Valid values are:

Compiler

String to replace the executable name in the compile flags. The name controls flag parsing (clang vs clang-cl), target inference (gcc-arm-noneabi) etc.

If the option matches a glob mentioned in --query-driver, then it’ll be invoked for extraction of include paths.

BuiltinHeaders

Controls whether Clangd should include its own built-in headers (like stddef.h), or use the system header found from the query driver.

Valid values are:

CompileFlags:
  BuiltinHeaders: QueryDriver

Note: if the driver is not clang, BuiltinHeaders: QueryDriver will result in the clang frontend (embedded in clangd) processing the builtin headers of another compiler, which could lead to unexpected results such as false positive diagnostics.

Index

Controls how clangd understands code outside the current file.

Index:
  Background: Skip     # Disable slow background indexing of these files.

clangd’s indexes provide information about symbols that isn’t available to clang’s parser, such as incoming references.

Background

Whether files are built in the background to produce a project index. This is checked for translation units only, not headers they include. Legal values are Build (the default) or Skip.

External

Used to define an external index source:

MountPoint can be used to specify source root for the index. This is necessary to handle relative path conversions. Overall schema looks like this:

Index:
  External:
    File: /abs/path/to/an/index.idx
    # OR
    Server: my.index.server.com:50051
    MountPoint: /files/under/this/project/

StandardLibrary

Controls whether clangd eagerly indexes the standard library (to give code completions of standard library symbols on an empty file). Sample block (default).

Index:
  StandardLibrary: true

Style

Describes the style of the codebase, beyond formatting.

FullyQualifiedNamespaces

Namespaces that should always be fully qualified, meaning no “using” declarations, always spell out the whole name (with or without leading::). All nested namespaces are affected as well. Affects availability of the AddUsing tweak.

QuotedHeaders

A list of regexes. Headers whose path matches one of these regexes are inserted using "" syntax.

AngledHeaders

A list of regexes. Headers whose path matches one of these regexes are inserted using <> syntax.

Example:

Style:
  QuotedHeaders: "src/.*"
  AngledHeaders: ["path/sdk/.*", "third-party/.*"]

Diagnostics

Suppress

Diagnostic codes that should be suppressed.

Valid values are:

This is a simple filter. Diagnostics can be controlled in other ways (e.g. by disabling a clang-tidy check, or the -Wunused compile flag). This often has other advantages, such as skipping some analysis.

ClangTidy

Configure how clang-tidy runs over your files.

The settings are merged with any settings found in .clang-tidy configuration files with the ones from clangd configs taking precedence.

Add

List of checks. These can be globs, for example Add: 'bugprone-*'.

Remove

List of checks to disable, can be globs.

This takes precedence over Add, this supports enabling all checks from a module apart from some specific checks.

Example to use all modernize module checks apart from use trailing return type:

Diagnostics:
  ClangTidy:
    Add: modernize*
    Remove: modernize-use-trailing-return-type

CheckOptions

Key-value pairs of options for clang-tidy checks. Available options for all checks can be found here.

Note the format here is slightly different to .clang-tidy configuration files as we don’t specify key: <key>, value: <value>. Instead just use <key>: <value>

Diagnostics:
  ClangTidy:
    CheckOptions:
      readability-identifier-naming.VariableCase: CamelCase

FastCheckFilter

Whether to run clang-tidy checks that may slow down clangd.

Valid values are:

Diagnostics:
  ClangTidy:
    FastCheckFilter: Strict

UnusedIncludes

Enables Include Cleaner’s unused includes diagnostics. Possible values: None, Strict (default since clangd 17).

Diagnostics:
  UnusedIncludes: Strict

Includes

IgnoreHeader

A list of regexes. Include Cleaner will not produce diagnostics for headers whose path is a suffix match for any of these.

AnalyzeAngledIncludes

A boolean that enables/disables detection of unused angled includes that are not from the Standard Library. Disabled by default to avoid false-positives caused by umbrella headers.

MissingIncludes

Enables Include Cleaner’s missing includes diagnostics. Possible values: None (default), Strict.

Completion

Configures code completion features. Sample block (default):

Completion:
  AllScopes: Yes
  ArgumentLists: FullPlaceholders
  HeaderInsertion: IWYU
  CodePatterns: All

AllScopes

Whether code completion should include suggestions from scopes that are not visible. The required scope prefix will be inserted. The default is Yes.

ArgumentLists

Determines what is inserted in argument list position when completing a call to a function. Here are the valid values and examples of the corresponding behaviour, assuming a function foo(int arg) exists (^ represents the cursor position):

The default is FullPlaceholders.

This option governs the completion of template names as well, where the delimiters are <>.

HeaderInsertion

Add #include directives when accepting code completions. Config equivalent of the CLI option --header-insertion. Valid values are:

CodePatterns

Completion will suggest code snippets and code patterns. Valid values are:

The default is All.

InlayHints

Configures the behaviour of the inlay-hints feature. Sample block (default):

InlayHints:
  BlockEnd: false
  Designators: true
  Enabled: true
  ParameterNames: true
  DeducedTypes: true
  DefaultArguments: false
  TypeNameLimit: 24

Enabled

A boolean that enables/disables the inlay-hints feature for all kinds, when disabled, configuration for specific kinds are ignored.

ParameterNames

A boolean that enables/disables inlay-hints for parameter names in function calls.

DeducedTypes

A boolean that enables/disables inlay-hints for deduced types.

Designators

A boolean that enables/disables inlay-hints for designators in aggregate initialization. (eg: Designators: true: std::vector<int> arr = {[0]= 1, [1]= 2} ; Designators: false: std::vector<int> arr = {1, 2})

BlockEnd

A boolean that enables/disables inlay-hints for block end comment. An example is shown below (comments are inlay hints):

void foo() {
  struct S {
  }; // struct S
} // foo

DefaultArguments

A boolean that enables/disables inlay hints for default arguments. Example:

void foo(int a, int b = 42);
void bar() {
  // This line will be displayed as `foo(a: 41, b: 42);`
  // The `a:` is the usual parameter hint.
  // The `, b: 42` is a default argument hint.
  foo(41);
}

TypeNameLimit

Character limit for type hints. Hints that would be longer are not shown. 0 means no limit.

Hover

Configures contents of the hover cards. Sample block (default):

Hover:
  ShowAKA: false

ShowAKA

A boolean that controls printing of desugared types, e.g: vector<int>::value_type (aka int)

Semantic Tokens

Configure semantic highlighting. Sample block (default):

SemanticTokens:
  DisabledKinds: []
  DisabledModifiers: []

DisabledKinds

Specify semantic token kinds that clangd should not send to client.

Available kinds could be found here in the Kind column.

DisabledModifiers

Specify semantic token modifiers that clangd should not send to client.

Available modifiers could be found here in the Modifier column.

✏️