clangd, Neovim, and compile_commands.json

C++ editor tooling works best when the editor sees the project the same way the compiler sees it. That sounds obvious, but it is the detail that makes the difference between a useful language server and one that reports false errors every few lines.

clangd is the language server from the LLVM project. It gives editors C and C++ features such as diagnostics, completion, go-to-definition, hover documentation, semantic highlighting, include insertion, rename, and cross-reference search. It does not replace the compiler. Instead, it continuously parses the project using the same Clang frontend infrastructure that powers clang++.

For that parsing to be accurate, clangd needs to know how every source file is compiled. That information usually lives in the build system: include directories, preprocessor definitions, language standard, warning flags, target options, and the compiler executable. The bridge between the build system and clangd is a JSON Compilation Database, normally written as compile_commands.json.

The Moving Parts

Mermaid diagram

The important point is that clangd does not understand a Makefile as a build system. It understands compiler command lines. compile_commands.json is the file that translates from the build system world into the language-server world.

What clangd Does

clangd runs as a background process started by the editor. When a C++ file is opened, the editor sends requests and notifications to clangd using the Language Server Protocol, usually called LSP.

Examples of LSP messages include:

  • The user opened src/main.cpp.
  • The file changed in memory.
  • The cursor is over this symbol; provide hover text.
  • Find the definition of this function.
  • Return completion items at this location.
  • Publish diagnostics for this file.

To answer those questions, clangd builds an internal view of the translation unit. In C++, a translation unit is not just the .cpp file. It is the .cpp file after preprocessing, including all headers, macros, #include paths, language standard settings, and compiler-specific options.

That means this command:

clang++ -std=c++20 -Iinclude -DGLFW_INCLUDE_VULKAN -c src/app.cpp -o build/app.o

can produce a very different parse from this command:

clang++ -std=c++11 -c src/app.cpp -o build/app.o

Both commands name the same source file, but they describe different C++ programs to the compiler frontend. If clangd guesses wrong, editor diagnostics become noisy and navigation becomes unreliable.

How Neovim Integrates With clangd

Modern Neovim includes a built-in LSP client. The usual setup is simple: install clangd, configure Neovim to start it for C and C++ files, and let the LSP client connect buffers to the server.

A minimal Neovim configuration looks like this:

vim.lsp.config.clangd = {
  cmd = { "clangd" },
  filetypes = { "c", "cpp", "objc", "objcpp", "cuda" },
  root_markers = { "compile_commands.json", ".git" },
}

vim.lsp.enable("clangd")

Plugin-based setups such as nvim-lspconfig express the same idea:

require("lspconfig").clangd.setup({})

Once attached, Neovim and clangd communicate continuously:

Mermaid diagram

The editor does not need to know the include paths itself. Neovim delegates that to clangd, and clangd reads the compilation database.

Why compile_commands.json Is Required

Without a compilation database, clangd falls back to guesses. Those guesses may work for small projects using only standard headers, but they fail quickly in real C++ projects.

Common symptoms include:

  • Headers such as GLFW/glfw3.h or Vulkan headers appear to be missing even though the project builds.
  • Types defined behind project-specific macros are reported as unknown.
  • C++20 or C++23 code is flagged as invalid because the server guessed an older standard.
  • go to definition jumps to the wrong overload or fails completely.
  • Completion suggestions omit project symbols that depend on generated or configured include paths.

A compile_commands.json file fixes this by listing one entry per source file:

[
    {
        "directory": "/home/user/project",
        "file": "src/app.cpp",
        "arguments": [
            "clang++",
            "-std=c++20",
            "-Iinclude",
            "-DGLFW_INCLUDE_VULKAN",
            "-c",
            "src/app.cpp",
            "-o",
            "build/app.o"
        ]
    }
]

The fields are straightforward:

  • directory is the working directory used for relative paths.
  • file is the source file this command compiles.
  • arguments is the compiler invocation split into an argument array.

clangd searches for compile_commands.json in the project root or parent directories. Many projects place it at the repository root so both the editor and command-line tools can find it.

Generating The Database From Make

Build systems such as CMake can generate compile_commands.json directly. Make does not have a built-in equivalent. A Makefile knows the compiler commands in its recipes, but it does not persist them as structured data for tools.

One reliable approach is to ask Make what it would run, without actually building anything, then convert the printed compile commands into JSON.

The core idea is:

Mermaid diagram

The generator can run make -n -B:

  • -n tells Make to print commands instead of executing them.
  • -B tells Make to consider all targets out of date.

The -B flag is important. Without it, an up-to-date project may produce Nothing to be done, and the generated database would be empty even though the build rules are valid.

After collecting the dry-run output, the generator should parse each command line with shell-style quoting rules, then keep only commands that look like C++ compilation steps. A simple and practical filter is:

  • The command contains a .cpp source file.
  • The command contains an -o output option.

That skips unrelated recipes such as directory creation, shader compilation, asset processing, or build probes.

For each compile command, the generated JSON entry stores:

  • The current project directory as directory.
  • The .cpp source path as file.
  • The full compiler command as arguments.

Sorting the entries by source file keeps the output stable. If the build flags have not changed, regenerating the file should produce no diff.

Automating It With Make

The generator should be part of the normal project workflow. Developers should not need to remember a separate Python command whenever compiler flags change.

A Makefile target can make the database a first-class project artifact:

.PHONY: compile-commands
compile-commands:
	./scripts/compile-commands.py

Then regenerate the database with:

make compile-commands

If the Makefile supports compiler overrides, the same target can generate commands for a different compiler:

CXX=clang++ make compile-commands

The target can also be connected to development setup commands:

.PHONY: setup
setup: compile-commands
	@printf 'development files are ready\n'

Or it can be made explicit in editor-oriented workflows:

.PHONY: lsp
lsp: compile-commands
	@printf 'clangd database updated\n'

The important rule is to regenerate compile_commands.json after changing compiler flags, include paths, source lists, or per-target options. The compilation database is a snapshot of how the project is built. When the build rules change, the snapshot must be refreshed.

Why Not Just Let Tools Intercept A Build?

Tools such as build interceptors can produce a compilation database by watching real compiler executions. That can work well, but it has a practical weakness: if the build is already up to date, no compiler commands run. The tool may then write an empty database or fail to update the previous one usefully.

A Make dry run avoids that state problem. It asks the build system to print what it would do if everything needed rebuilding. This keeps the Makefile as the single source of truth while still producing deterministic editor metadata.

The Payoff

When compile_commands.json is accurate, clangd stops guessing. Neovim gets diagnostics that match the real build, completion understands project headers and macros, and navigation follows the same translation units the compiler sees.

That is the core loop:

Mermaid diagram

For C++ projects built with Make, generating compile_commands.json is not optional editor polish. It is the contract that lets language tooling understand the project correctly.