Merge compile commands

[yiftahw]

Abstract

• Merge multiple compile_commands.json on the fly whenever they are added/changed based on a configuration saved in .vscode/settings.json
• closes Support multiple compile commands files per project microsoft/vscode-cpptools#7029
• compilation database merging logic based on VSCode CMake Tools PR #2029
• glob patterns are not supported in this PR (explained why below)

Usage

define the following entries in .vscode/settings.json:

// already implemented
"C_Cpp.default.compileCommands": "${workspaceFolder}/build/merged_compile_commands.json",
// new
"C_Cpp.mergeCompileCommands": { 
"sources": [
        "${workspaceFolder}/build/proj1/compile_commands.json",
        "${workspaceFolder}/build/proj2/compile_commands.json",
    ],
    "destination": "${workspaceFolder}/build/merged_compile_commands.json"
},

• NOTE: "C_Cpp.default.compileCommands" is not changed (to a list) for backwards compatibility.

Why are glob patterns not supported here?

• the CMake Tools extension supports glob patterns without consuming heavy CPU resources as it only tries to recursively search for compile_commands.json files when a build is finished succesfully. (one time per build process)
• the C/C++ extension doesn't know when a build is started (or finished), it will need to recursively monitor files constantly.
  • can create a non-negligible and persistent CPU load if directories contain many files.
  • will trigger many false positive events.

Error Handling

• files defined in "sources" don't exist
  • how would we notify the user? (should we?)
  • there are currently no squiggles in settings.json
  • logs in C++ Configuration Errors are used exclusively by the native language server
  • error popups seems excessive for this kind of error
• cannot create the destination folder/file (permissions, invalid path)
  • error popup seems ok in this scenario
• compile_commands.json can't be parsed
  • error popup seems ok in this scenario

State Machine

stateDiagram-v2 
[*] --> load : settings.json loaded/changed
load : close file watchers<br>load configuration
check_dst: check if destination file exists
load --> check_dst
create : merge compile commands
check_srcs : check if any of the sources<br>is newer than dst
check_dst --> check_srcs : true
check_dst --> create : false
missingbank : periodically check if missing files are created
filewatchers : create source file watchers
check_srcs --> filewatchers: false
check_srcs --> create : true
missingbank --> filewatchers : file created
filewatchers --> missingbank : error<br>file missing
filewatchers --> create : source file changed
filewatchers --> check_dst : error<br>file watcher limit hit
create --> filewatchers : Success
create --> [*] : Error

Loading

TODO:

• implement periodic file watchers on non-existant files
• finalize error handling/user notifications scheme
• some validation in settings.ts in getMergeCompileCommands()
• add tests
• remove console.log() prints