[clangd] header insertion mappings

[yshui]

When writing OpenGL programs that use libepoxy, clangd really wants to include epoxy/gl_generated.h for any OpenGL API calls I use. But the correct way to use libepoxy is to include epoxy/gl.h (source).

Is there a way I can tell which header is the correct one to include. Maybe we can have a header mapping option, like:

Completion:
  HeaderMap:
    "epoxy/gl_generated.h": epoxy/gl.h
    ...

[llvmbot]

@llvm/issue-subscribers-clangd

Author: Yuxuan Shui (yshui)

When writing OpenGL programs that use libepoxy, clangd really wants to include `epoxy/gl_generated.h` for any OpenGL API calls I use. But the correct way to use libepoxy is to include `epoxy/gl.h` ([source](https://github.com/anholt/libepoxy?tab=readme-ov-file#switching-your-code-to-using-epoxy)).

Is there a way I can tell which header is the correct one to include. Maybe we can have a header mapping option, like:

Completion:
  HeaderMap:
    "epoxy/gl_generated.h": epoxy/gl.h
    ...

[EugeneZelenko]

If clangd uses clang-include-cleaner, see its documentation for proper fix: https://clangd.llvm.org/design/include-cleaner. For example Qt headers were fixed by adding relevant annotations.

[yshui]

Would I need to add IWYU pragmas to epoxy/gl_generated.h? I can't do that to headers I don't control...

[EugeneZelenko]

No, you need to request to add pragma(s) to epoxy/gl.h. Sure, it may take some effort to convince maintainer to do so. I was not so lucky in case of Python.h :-(

[HighCommander4]

Maybe we can have a header mapping option, like:

Completion:
  HeaderMap:
    "epoxy/gl_generated.h": epoxy/gl.h
    ...

This is on file as clangd/clangd#1367; I'll close this as a duplicate.