CMake compile_commands.json and add_custom_command generated header interoperability

Direct Answers

1. Does CMake intend compile_commands.json to represent compiler invocations for files produced by add_custom_command? No. The JSON is a compilation database emitted at configure time. It contains one entry per source file that a target compiles. Custom command outputs are not compiled, so they never appear.

2. Should language servers treat missing generated-header entries as a CMake configuration gap or external tooling responsibility? External tooling responsibility. The compilation database schema has no field for generated-file provenance. CMake’s contract ends at recording compiler invocations; build-graph inference belongs to the consumer.

3. Is a prior build required before compile_commands.json can support symbol resolution for generated headers? Yes. The generated header must exist on disk and be reachable through the target’s include directories. compile_commands.json alone does not create the file.

Confirmed Behavior (CMake 3.x, Ninja / Unix Makefiles)

• CMAKE_EXPORT_COMPILE_COMMANDS=ON writes compile_commands.json during configure. Entries are compiler invocations for target sources only.
• add_custom_command and add_custom_target invocations are never emitted.
• The compilation database schema (used by clangd, ccls, etc.) lacks a standard field for generation commands or provenance.
• CMake treats the JSON as a compilation database, not a full build graph. Generation steps are build-system concerns outside the JSON contract.

Practical Consequence

A language server can resolve symbols from a generated header only when:

1. The header file exists on disk (after the custom command runs).
2. The header’s directory is listed in the consuming target’s include_directories or target_include_directories.
3. The compilation database entry for the consuming source points to a working directory where the include path resolves.

Until a build (or at least the custom command) runs, the file is absent and symbol resolution fails.

Minimal Working Setup

# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(GenHeaderDemo LANGUAGES CXX)

set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

add_custom_command(
  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated.h
  COMMAND ${CMAKE_COMMAND} -E echo \"#define ANSWER 42\" > ${CMAKE_CURRENT_BINARY_DIR}/generated.h
  COMMENT \"Generating header\"
)

add_library(mylib src.cpp)
target_include_directories(mylib PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
add_custom_target(gen-header DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/generated.h)
add_dependencies(mylib gen-header)

After configure, compile_commands.json has an entry for src.cpp only. Run cmake --build build --target gen-header (or a full build) so generated.h appears. Then the language server can resolve ANSWER in src.cpp.

Diagnostic Check

If symbol resolution still fails after the header exists, verify that the consuming target’s compile command in compile_commands.json includes -I (or the directory is a system include). What generator and CMake version are you using? The exact include-flag spelling can differ between Ninja and Makefiles.