Make compile_commands.json support working directories relative to compile_commands.json

[carlynorama]

Description / Motivation

Right now the compile_commands.json "directory" field only works with absolute paths.

In many projects this isn't a problem as they're generated by a build tool and live in a version control ignored folder anyway.

Since Swift doesn't have headers exposed like C/C++ projects, sourcekit-lsp understandably relies on this file to sort out relationships in the code when a project uses the compileDatabase project mode.

On large projects, monorepos, example code, open source projects, etc. expecting a build to happen before a cloned repository is parsable by an IDE could be a point of friction.

It would help these projects gain adoption if they could include a ready made absolute path free compile_commands.json file so an IDE can make sense of them more quickly, thereby avoiding giving a naive user the impression that something is wrong when it is not.

Details

For example right now an entry will have an absolute link for the directory with possibly relative links to that directory. That will be unusable, and frankly insecure, for sharing.

  {
    "directory": "/Users/someUser/Developer/project/CustomBuildFolderName",
    "command": "swiftc -j 10 -num-threads 10 -c -module-name MyApp -incremental ../SomeSourceFolder/main.swift ../SomeSourceFolder/extra.swift",
    "file": "../SomeSourceFolder/main.swift"
  }

Imagining a compile_commands.json in the root directory of the project, one can remove all the user/user hardware related information with a relative link.

  {
    "directory": "CustomBuildFolderName",
    "command": "swiftc -j 10 -num-threads 10 -c -module-name MyApp -incremental ../SomeSourceFolder/main.swift ../SomeSourceFolder/extra.swift",
    "file": "../SomeSourceFolder/main.swift"
  }

Imagining a compile_commands.json in a custom folder one level down:

  {
    "directory": "../CustomBuildFolderName",
    "command": "swiftc -j 10 -num-threads 10 -c -module-name MyApp -incremental ../SomeSourceFolder/main.swift ../SomeSourceFolder/extra.swift",
    "file": "../SomeSourceFolder/main.swift"
  }

Passing a relative root to clang and having it generate the absolute for itself does seem to have potential support in clangd:

https://reviews.llvm.org/D53481

Barriers/Alternatives

Not everyone can do the transformations in their head when multiple points for relative links are being used, especially within in the same document. Any documentation will have to make clear about the difference in relative links for "directory" (relative to the current file) and for "file"/"command"/"arguments" (relative to "directory").

Also in the case that the developer is using a build folder or custom location for their compile_commands.json it would be easy to assume that relative paths would be to the project root instead of the file, especially if that is what one just did in the .config. Since "project/workspace root" is a conceptual place that can be hard to pin down and "current file" has a more practical basis, relative to file still seems like the best choice.

Since relative to the current file conventions are very common it seems like these two concerns can be easily addressed with documentation and examples.

Drift between what Swift projects will accept and other clang projects expect from a compile_commands.json might be a problem, but since other tools in the community (clangd) will accept relative roots, there may be a path forward there.

[ahoppen]

Synced to Apple’s issue tracker as rdar://142317810