[all-commits] [llvm/llvm-project] 8976a1: VFS: Document goals of 'use-external-name' and rel...

[Duncan P. N. Exon Smith via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: 8976a1e111393aab7b4965196364ad734a17f2d5
      https://github.com/llvm/llvm-project/commit/8976a1e111393aab7b4965196364ad734a17f2d5
  Author: Duncan P. N. Exon Smith <dexonsmith at apple.com>
  Date:   2021-09-01 (Wed, 01 Sep 2021)

  Changed paths:
    M clang/lib/Basic/FileManager.cpp
    M clang/unittests/Basic/FileManagerTest.cpp
    M llvm/include/llvm/Support/VirtualFileSystem.h

  Log Message:
  -----------
  VFS: Document goals of 'use-external-name' and related logic, NFC

Document 'use-external-name' and the various bits of logic that make it
work, to avoid others having to repeat the archival work (given that I
added getFileRefReturnsCorrectNameForDifferentStatPath to
FileManagerTest, seems possible I understood this once before!).

- b59cf679e81483cbb3a9252056b7528f4c49586c added 'use-external-name' to
  RedirectingFileSystem. This causes `stat`s to return the external
  name for a redirected file instead of the name it was accessed by,
  leaking it through the VFS.
- d066d4c849be06a01c0d17e8dc206913f4e7bfe3 propagated the external name
  further through clang::FileManager.
- 4dc5573acc0d2e7c59d8bac2543eb25cb4b32984, which added
  clang::FileEntryRef to clang::FileManager, has complicated concession
  to account for this as well (since refactored a bit).

The goal of 'use-external-name' is to enable Clang to report "real" file
paths to users (via diagnostics) and to external tools (such as
debuggers reading debug info and build systems reading `.d` files).

I've added FIXMEs to look at other channels for communicating the
external names, since the current implementation adds complexity to
FileManager and exposes an inconsistent interface to clients.

Besides that, the FileManager logic appears to be kicking in outside of
'use-external-name'. Seems that *some* vfs::FileSystem implementations
canonicalize some paths returned by `stat` in *some* cases (the bug
isn't fully understood yet). Volodymyr Sapsai is investigating, this at
least better documents what *is* understood.