Header copies in build and install directories break code tools (live inspection, refactoring, navigation)

Description of Issue

USD compiles against copies of the headers in the build and install directories, instead of the source directory headers. This completely breaks tool support for headers. Code navigation and refactoring uses the copies (which you're not supposed to edit), and live analysis doesn't see the modifications to the actual headers until you actually build, so it doesn't work. This is a frustrating development experience.

The code tools are simply not aware of the existence of the source headers, since they're not part of any compilation command. And if you do manually edit header search paths to make them visible, you just end up with ambiguous header errors, because there's no way to remove the actual compilation paths from the header paths.

I understand that headers are handled this way to allow separating private from public, using the build directory for private, and the install directory for public. But this is a rather odd compilation model that just doesn't work with typical C/C++ code tools. The source headers used for compilation are always expected to be found in their original include directories.

I'm curious to know how this is handled internally. Is there are workaround that I'm not aware of?

The simplest and least disruptive fix I can think of is to create symlinks to private and public directories in the build path, instead of using copies. The public headers are still copied to the install directory, but are not used for compilation, instead it's the symlinks in the build directory that are used. CMake has portable symlink support (even Windows) using -E create_symlink.

Steps to Reproduce

N/A

System Information (OS, Hardware)

I've had this issue with CLion and VS Code (on macOS, Linux and Windows), using both CMake and compilation database integrations.

Package Versions

N/A

Build Flags

N/A

PixarAnimationStudios / OpenUSD