msbuild-compdb

Generate a Clang compile_commands.json from MSBuild — for C++ projects built with Visual Studio solutions (.sln / .vcxproj) and the MSVC CL.exe toolchain.

msbuild-compdb makes MSBuild-based C++ projects usable in editors and tooling that rely on a compilation database — clangd, clang-tidy, and other Clang-based tools — so you get code navigation, completion, and diagnostics outside Visual Studio (for example in Neovim).

Why

Language servers like clangd don't understand .sln / .vcxproj directly; they work from a compile_commands.json. Visual Studio doesn't produce one. msbuild-compdb bridges that gap by reconstructing the real CL.exe compile commands from a build and emitting a standard compilation database.

Features

• Two modes: parse an existing binary log (.binlog), or build a solution/project and parse the result — both from a single executable.
• Recovers the exact CL.exe command line per source file.
• Adds the system/SDK/vcpkg include directories (which CL normally takes from the INCLUDE environment variable) as clang-cl /imsvc flags, so clangd resolves standard and Windows headers even when launched outside a VS developer shell.
• Emits one entry per source file, as the compilation database format expects.
• Recognizes .cpp, .cc, .cxx, .c++, and .c sources.
• Ships as a single self-contained .exe — no .NET runtime required on the target machine.

Install

Download

Grab the latest msbuild-compdb.exe from the releases page and drop it anywhere on your PATH (or bundle it with your editor plugin).

Build from source

Requires the .NET SDK (8.0 or newer):

git clone https://github.com/max-wolf-cpp/msbuild-compdb.git
cd msbuild-compdb
dotnet publish MSBuildCompDb/MSBuildCompDb.csproj -c Release -o ./artifacts

The single-file executable is produced at ./artifacts/msbuild-compdb.exe.

Usage

msbuild-compdb --binlog <path.binlog>          [--output compile_commands.json]
msbuild-compdb --build  <path.sln|.vcxproj>    [--output compile_commands.json] [-- <msbuild args>]

Option	Description
-i, --binlog	Parse an existing MSBuild binary log.
-b, --build	Build the project/solution (msbuild /bl) and parse the result.
-o, --output	Output path (default: compile_commands.json).
-h, --help	Show help.

Everything after -- is forwarded verbatim to MSBuild, e.g. to pick a configuration:

msbuild-compdb --build MySolution.sln -- /p:Configuration=Debug /p:Platform=x64

From an existing binary log

Build your project with binary logging enabled, then convert it:

msbuild MySolution.sln /bl:msbuild.binlog
msbuild-compdb --binlog msbuild.binlog --output compile_commands.json

Building in one step

If you'd rather not produce a binlog yourself, let the tool run the build (it locates MSBuild via vswhere):

msbuild-compdb --build MySolution.sln --output compile_commands.json

Example output

[
  {
    "directory": "E:/Projects/MyGame/Engine",
    "command": "\"C:/.../CL.exe\" /c /I... /std:c++20 /imsvc \"C:/.../MSVC/.../include\" Source/Engine.cpp",
    "file": "E:/Projects/MyGame/Engine/Source/Engine.cpp"
  }
]

The command keeps MSVC-style flags and CL.exe as the driver; clangd detects this and switches to clang-cl mode, so /I, /D, /std:c++20, etc. are understood as-is.

How it works

msbuild-compdb reads the binary log with MSBuild.StructuredLogger, then for every CL task:

1. extracts the full CL.exe command line from the task's messages;
2. determines the owning project's directory;
3. splits out each source file into its own database entry;
4. reads the project's IncludePath property and appends the system include directories as /imsvc flags;
5. writes a standard compile_commands.json.

Editor integration

Point clangd at the generated database (place it at your project root, or pass --compile-commands-dir). In Neovim this works with nvim-lspconfig / clangd, or with build-plugins that manage clangd for you.

Scope & non-goals

Focused on Windows + MSBuild + Visual Studio C++ projects + CL.exe. It does not aim to replace MSBuild, parse .sln/.vcxproj directly, or support arbitrary compilers and build systems.

Limitations

• Only compile commands present in the build (binlog) can be reconstructed.
• Windows / MSVC CL.exe only; other toolchains are out of scope.
• Behavior depends on how MSBuild logged the compiler invocation; unusual or generated project layouts may need adjustments.

License

MIT © Max Wolf