clangd

Display available options

$ clangd --help

$ clangd --help-list

$ clangd --version

clangd [options]

clangd is typically run as a background process by an editor, communicating over standard I/O using the Language Server Protocol. Its command-line options control its behavior and logging.

--compile-commands-dir=<path>
    Specifies the directory containing the compile_commands.json file, crucial for accurate project understanding.

--fallback-style=<name>
    Sets the fallback code style for formatting when no .clang-format file is found in the project.

--log=<value>
    Controls the verbosity of logging output (e.g., info, verbose, debug) to stderr.

--project-root=<path>
    Explicitly sets the project root directory, overriding `clangd`'s auto-detection.

--query-driver=<paths>
    A comma-separated list of compiler paths to query for system include directories and default compilation flags.

--trace
    Enables logging of all LSP traffic (incoming and outgoing JSON-RPC messages) for debugging purposes.

--version
    Displays the clangd version information and then exits.

--background-index
    Enables background indexing of the project files to provide faster responses for queries like workspace symbols or find all references.

clangd is a Language Server Protocol (LSP) server for C, C++, and Objective-C, part of the LLVM project. It provides advanced IDE-like features to any LSP-compatible editor (e.g., VS Code, Neovim, Emacs, Sublime Text). These features include intelligent code completion, on-the-fly diagnostics (errors and warnings), go-to-definition, find-all-references, symbol renaming, and code formatting.

clangd parses your code using Clang's powerful parsing engine, leveraging compile_commands.json files for accurate build configuration. This allows it to understand your project's compilation flags and include paths, providing highly accurate and context-aware language features. It significantly enhances developer productivity by bringing robust C-family language support to lightweight editors.

Accuracy relies on compile_commands.json: For optimal accuracy in diagnostics and navigation, clangd heavily relies on a correctly generated compile_commands.json file, which specifies compilation flags for each source file. Without it, clangd might guess flags or use a fallback, potentially leading to less accurate results.

Resource Usage: For very large C++ codebases, clangd can consume significant memory and CPU resources, especially during initial indexing or extensive refactoring operations.

Editor Integration: While it implements a standard protocol, the quality and feature set of clangd integration can vary between different editors due to how each editor's LSP client is implemented.

While command-line flags control clangd's behavior, its core understanding of your project comes from configuration files:

• compile_commands.json: Generated by build systems (like CMake or Ninja) or tools (like bear), this file tells clangd how each source file is compiled, including include paths and defines. It's crucial for accurate diagnostics and navigation.
• .clangd: A project-specific configuration file for clangd itself, allowing for settings like specific compilation flags, logging levels, or disabled features.
• .clang-format: Used by clangd for code formatting operations, defining coding style rules for the project.

clangd communicates with editors using JSON-RPC messages over standard input/output, adhering to the Language Server Protocol specification. This design allows it to be integrated into a wide range of editors and IDEs that support LSP, ensuring a consistent development experience across different environments.

clangd emerged as part of the broader LLVM project, leveraging the highly robust and accurate parsing capabilities of Clang, the LLVM C/C++/Objective-C frontend. Its development gained momentum with the rise of the Language Server Protocol (LSP), aiming to provide a modern, universal, and editor-agnostic solution for C-family language development.

Before clangd and LSP, editor integrations for C++ were often editor-specific or relied on less precise tag-based systems. clangd was designed to overcome these limitations by offering deep semantic understanding powered by a real compiler frontend, establishing itself as a leading language server for C++ development.

clang(1), llvm(1), cmake(1), bear(1)