Code Compile Commands and Language Toolchains

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

Compile commands tell code-intelligence tools how each file is actually built, including include paths, language standard, target, macros, and compiler driver.

## Core Explanation

Parsing code is not just reading text. C and C++ tools in particular need the same command-line context that the compiler would receive. Without that context, an agent can report false diagnostics, miss declarations, or navigate to the wrong symbol definition.

Agents should inspect compile_commands.json, build directory, compiler path, sysroot, include search paths, language standard flags, generated headers, and whether the file is a header with an inferred command.

## Source-Mapped Facts

- Clang documentation describes the JSON Compilation Database as recording compile options for source files in a project. ([source](https://clang.llvm.org/docs/JSONCompilationDatabase.html))
- CMake documentation says CMAKE_EXPORT_COMPILE_COMMANDS generates a compile_commands.json file containing exact compiler calls for all translation units. ([source](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html))
- clangd documentation says a compilation database can be a compile_commands.json file that lists commands for each file. ([source](https://clangd.llvm.org/design/compile-commands))

## Further Reading

- [Clang JSON Compilation Database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
- [CMake CMAKE_EXPORT_COMPILE_COMMANDS](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html)
- [clangd Compile Commands](https://clangd.llvm.org/design/compile-commands)