Move RedirectingFileSystem interface into header.

[JDevlieghere]

Summary

This moves the RedirectingFileSystem into the VFS header so we can extend it from LLVM with a custom implementation to get the external path.

[vsapsai]

How do you want it to work with symlinks? Would getRealPath be sufficient for your purpose?

[JDevlieghere]

In D54277#1292180, @vsapsai wrote:

How do you want it to work with symlinks? Would getRealPath be sufficient for your purpose?

I'm not sure how those two are related, other than the confusing name. As far as I can tell this only wraps the realpath(3) call, which is definitely much too expensive to do in the "real" file system case. For symlinks I wouldn't really care, it's up to the user to resolve them if they matter.

[vsapsai]

In D54277#1292267, @JDevlieghere wrote:

In D54277#1292180, @vsapsai wrote:

How do you want it to work with symlinks? Would getRealPath be sufficient for your purpose?

I'm not sure how those two are related, other than the confusing name. As far as I can tell this only wraps the realpath(3) call, which is definitely much too expensive to do in the "real" file system case. For symlinks I wouldn't really care, it's up to the user to resolve them if they matter.

OK. Now I understand that you prefer to avoid realpath as it is too expensive for this purpose.

Do you think Optional is sufficient for handling errors? On one hand it is a simpler interface but on the other hand it loses information why external path might be unavailable.

lib/Support/VirtualFileSystem.cpp

1906–1907

Need to double check but at the first glance I have reservations about a case with nested RedirectingFileSystem. Should getExternalPath go only through 1 level of indirection or all the way to real file system?

[JDevlieghere]

In D54277#1293988, @vsapsai wrote:

In D54277#1292267, @JDevlieghere wrote:

In D54277#1292180, @vsapsai wrote:

How do you want it to work with symlinks? Would getRealPath be sufficient for your purpose?

I'm not sure how those two are related, other than the confusing name. As far as I can tell this only wraps the realpath(3) call, which is definitely much too expensive to do in the "real" file system case. For symlinks I wouldn't really care, it's up to the user to resolve them if they matter.

OK. Now I understand that you prefer to avoid realpath as it is too expensive for this purpose.

Do you think Optional is sufficient for handling errors? On one hand it is a simpler interface but on the other hand it loses information why external path might be unavailable.

Yeah, I wasn't sure about this. Usually the client won't care what the error is, but there's no harm in returning an ErrorOr<>. I'll update the patch!

[JDevlieghere]

lib/Support/VirtualFileSystem.cpp

1906–1907

Good point. My use case would require all the way to the real FS.

[sammccall]

I don't understand the concept of an "external path". What is it in the general case, when would you want to pass a path through this function vs using it directly?

From the patch description, it sounds like it may be specific to LLDB and/or RedirectingFileSystem. If so, maybe it shouldn't be on the interface?

[JDevlieghere]

In D54277#1296175, @sammccall wrote:

I don't understand the concept of an "external path". What is it in the general case, when would you want to pass a path through this function vs using it directly?

From the patch description, it sounds like it may be specific to LLDB and/or RedirectingFileSystem. If so, maybe it shouldn't be on the interface?

It's true that this is only relevant for VFS implementations that are somehow backed by disk. I'm curious what you have in mind. How would it not be on the interface and still work transparently?

[sammccall]

In D54277#1296400, @JDevlieghere wrote:

In D54277#1296175, @sammccall wrote:

I don't understand the concept of an "external path". What is it in the general case, when would you want to pass a path through this function vs using it directly?

From the patch description, it sounds like it may be specific to LLDB and/or RedirectingFileSystem. If so, maybe it shouldn't be on the interface?

It's true that this is only relevant for VFS implementations that are somehow backed by disk. I'm curious what you have in mind. How would it not be on the interface and still work transparently?

I can't really answer these questions without knowing what an external path is or when you'd want to use it.
Could you describe it here or add some documentation to the patch?

[JDevlieghere]

In D54277#1296661, @sammccall wrote:

In D54277#1296400, @JDevlieghere wrote:

In D54277#1296175, @sammccall wrote:

I don't understand the concept of an "external path". What is it in the general case, when would you want to pass a path through this function vs using it directly?

From the patch description, it sounds like it may be specific to LLDB and/or RedirectingFileSystem. If so, maybe it shouldn't be on the interface?

It's true that this is only relevant for VFS implementations that are somehow backed by disk. I'm curious what you have in mind. How would it not be on the interface and still work transparently?

I can't really answer these questions without knowing what an external path is or when you'd want to use it.
Could you describe it here or add some documentation to the patch?

I'll try here first and we can always improve the patch later.

Let's start from the beginning: I'm adding reproducer functionality to LLDB. Just like in clang, we need files to be available somewhere else form where they actually live on disk. This should also be transparent to the consumer. I want to use the VFS for this rather than hand-rolling my own implementation in LLDB. I did a whole bunch of refactoring to make most of LLDB's file system operations go through the VFS.

One notable difference between llvm/clang and LLDB is how the latter deals with files. In addition to using memory buffers, LLDB manipulates the majority of files through file pointers (FILE*) and file descriptors. It's also a lot less explicit in whether it's opening a file for reading or writing. By this I mean in llvm we have functions like openMemoryBufferForWriting or openMemoryBufferForReading while in LLDB we would just pass a different open flag. While I would love to change how LLDB manipulates files, I simply don't have the bandwidth to do that right now. So that brings me to my current problem: how do I access files from LLDB through the VFS.

I considered extending the VFS API with functions to provide access to file pointers and descriptors, but decided against it. The reason is that (AFAIK) there's no way to access memory through either of those on both windows and unix. I believe you can have a FILE*to memory but that doesn't work on Windows. File descriptors to memory don't make sense on either.

The alternative, proposed in this patch, is to have an API in the VFS to access the "underlying" file through its "external path". This is the path specified in YAML by external-contents. So when the VFS thinks that the file foo lives at /root/foo but it actually lives at /root/whatever/reproducer/foo, I want to be able to get that latter path and open it with (f)open.

Please let me know if this makes things more clear.

[sammccall]

In D54277#1297570, @JDevlieghere wrote:

In D54277#1296661, @sammccall wrote:

In D54277#1296400, @JDevlieghere wrote:

In D54277#1296175, @sammccall wrote:

I don't understand the concept of an "external path". What is it in the general case, when would you want to pass a path through this function vs using it directly?

From the patch description, it sounds like it may be specific to LLDB and/or RedirectingFileSystem. If so, maybe it shouldn't be on the interface?

It's true that this is only relevant for VFS implementations that are somehow backed by disk. I'm curious what you have in mind. How would it not be on the interface and still work transparently?

I can't really answer these questions without knowing what an external path is or when you'd want to use it.
Could you describe it here or add some documentation to the patch?

I'll try here first and we can always improve the patch later.

One notable difference between llvm/clang and LLDB is how the latter deals with files. In addition to using memory buffers, LLDB manipulates the majority of files through file pointers (FILE*) and file descriptors. It's also a lot less explicit in whether it's opening a file for reading or writing. By this I mean in llvm we have functions like openMemoryBufferForWriting or openMemoryBufferForReading while in LLDB we would just pass a different open flag. While I would love to change how LLDB manipulates files, I simply don't have the bandwidth to do that right now. So that brings me to my current problem: how do I access files from LLDB through the VFS.

So if I understand correctly, you want a way to devirtualize the VFS: to take a VFS file and get a concrete FILE* out of it. (In this case, via the filename and fopen()).

The fact that VFS doesn't have any way to do this is an important property, it's what makes the file system virtual.
VFS allows code to work in the same way on OS-native, in-memory, or distributed filesystems, and getExternalPath would break that - any code that called it can only work when the files are 1:1 with native OS files. Code that wants to couple to the FS implementation in this way shouldn't work transparently with VFS, because it breaks the design goal that VFSes are substitutable.

For what you're trying to do, I'd suggest one of the following:

• use a concrete VFS implementation that maps files and exposes the functions you need (e.g. expose RedirectingFileSystem from VFS.h with an appropriate public interface)
• use the existing getRealPath if you know which concrete VFSes you're using and it happens to do what you want
• track the correspondence between virtual and real paths externally (where you set up the FS)
• decouple LLDB's IO from the concrete filesystem (use VFS file instead of FILE*)

[JDevlieghere]

Thanks for bearing with me on this, Sam. I really appreciate you taking the time to find the best solution that works for all of us.

In D54277#1298127, @sammccall wrote:

So if I understand correctly, you want a way to devirtualize the VFS: to take a VFS file and get a concrete FILE* out of it. (In this case, via the filename and fopen()).

The fact that VFS doesn't have any way to do this is an important property, it's what makes the file system virtual.
VFS allows code to work in the same way on OS-native, in-memory, or distributed filesystems, and getExternalPath would break that - any code that called it can only work when the files are 1:1 with native OS files. Code that wants to couple to the FS implementation in this way shouldn't work transparently with VFS, because it breaks the design goal that VFSes are substitutable.

For what you're trying to do, I'd suggest one of the following:

• use a concrete VFS implementation that maps files and exposes the functions you need (e.g. expose RedirectingFileSystem from VFS.h with an appropriate public interface)

I guess this could work if we ignore the concern Volodymyr raised. If we assume that the ExternalFS is the RealFileSystem this could work. The problem is that RedirectingFileSystem takes any FileSystem as its external file system so if that doesn't have the right API we can't "dig deeper".

• use the existing getRealPath if you know which concrete VFSes you're using and it happens to do what you want.

This is not a viable option because it defeats the purpose of the VFS.

• track the correspondence between virtual and real paths externally (where you set up the FS)

This is not a viable option because it defeats the purpose of the VFS.

• decouple LLDB's IO from the concrete filesystem (use VFS file instead of FILE*)

This is also not a viable option because, like I said earlier, this would be too big of a change for LLDB. In addition to the risk such a change brings, I don't have the bandwidth for it and even if I did I'm not sure it be feasible. Pavel said he looked into this and found that some of LLDB's dependencies formed a problem.

I'll update the patch to reflect what (1) would look like.

[JDevlieghere]

I've added an interface ExternalFileSystem (I'm open to a better name) which has a slightly different meaning than before as will become clear later.

There's currently two implementations of this interface:

• The real filesystem.
• The redirecting filesystem.

The implementation for both is trivial. For the real file system it's a no-op. For the redirecting file system it does the translation. It's different from the previous patch in that it follows only one level of indirection. If a RedirectingFileSystem is backed by an in-memory file system it still works, you just get the translated path.

I strongly believe the interface is better than exposing the RedirectingFileSystem because it (1) hides more abstraction and (2) allows me to transparently switch between the two in LLDB.

[sammccall]

Hi Jonas,

I'm not sure about this abstraction: because it's non-recursive, it's hard to give meaningful semantics to getExternalPath() - the thing that would be useful to LLDB (if abstraction-breaking) is "native OS path", but for a general VFS, getExternalPath may give a native path, fail, or give a string that's not a native OS path.
If dispatching between the real VFS and redirecting VFS in this way is the best thing for LLDB, I'd suggest exposing RedirectingFS and adding the indirection on the LLDB side.

I think *if* VFS is to support devirtualization, then putting it on the main VFS interface so it can be recursive as in your original patch is the right way to do it, and it needs to be explicitly optional. (i.e. supporting devirtualization is a dynamic property rather than a static one.)

For example:

// If \p Path corresponds directly to a native operating system path, attempts to return that path.
// (e.g. if this is the native file system, or merely remaps paths for an underlying native file system).
// May return `None` if there is no such native file or its path cannot be determined.
virtual Optional<std::string> getNativeOSPath(StringRef Path) { return None; }

(Note the lack of "error" return value: this makes it safe for VFSes that don't implement this to not distinguish between the "no file" and "can't be determined" case)

But I don't personally think this addition is a good idea at the VFS layer. The upside is it allows LLDB to use VFS in some places, which may eventually turn into true VFS support. The risk is that adding an escape hatch will mean over time we can no longer rely on VFS-aware code being compatible with all VFSes.

I think this could benefit from a discussion in the wider LLVM community - I'll start a discussion on llvm-dev.

[JDevlieghere]

Move RedirectingFileSystem interface into header so we can extend it from LLDB.

[JDevlieghere]

ping

[kristina]

I'm not sure if this is way out of scope for this patch, but if I understand correctly this could be used for extending it to, for example, handle things like Perforce-style paths which could indeed be useful, although I'm not sure if that is possible (ie. would //depot/asdf behave differently on Windows and Linux/Darwin/any other OS that uses Unix-style paths?). If this is with the intention to allow extending RedirectingFileSystem downstream then I think it may be worth splitting it up from the YAML based implementation altogether, allowing custom path handling where needed (as a separate downstream extension), with the concrete reference implementation of RedirectingFileSystem (the YAML based one) being a separate thing. This would make it more extensible from the POV of downstream forks that may desire to implement path redirection that is too complicated to do using YAML mappings, but still fundamentally rely on some sort of path remapping.

Do you think it would be worth decoupling RedirectingFileSystem from YAML for such use cases and exposing both RedirectingFileSystem and, for your use case, something like YAMLRedirectingFileSystem? Just a stray thought, not really sure if it makes sense or is out of scope here (I don't believe it is, since if the interface is being exposed, it may be worth rethinking how it is layered if it's to be exposed through LLVMSupport headers).

[JDevlieghere]

In D54277#1332261, @kristina wrote:

I'm not sure if this is way out of scope for this patch, but if I understand correctly this could be used for extending it to, for example, handle things like Perforce-style paths which could indeed be useful, although I'm not sure if that is possible (ie. would //depot/asdf behave differently on Windows and Linux/Darwin/any other OS that uses Unix-style paths?). If this is with the intention to allow extending RedirectingFileSystem downstream then I think it may be worth splitting it up from the YAML based implementation altogether, allowing custom path handling where needed (as a separate downstream extension), with the concrete reference implementation of RedirectingFileSystem (the YAML based one) being a separate thing. This would make it more extensible from the POV of downstream forks that may desire to implement path redirection that is too complicated to do using YAML mappings, but still fundamentally rely on some sort of path remapping.

Do you think it would be worth decoupling RedirectingFileSystem from YAML for such use cases and exposing both RedirectingFileSystem and, for your use case, something like YAMLRedirectingFileSystem? Just a stray thought, not really sure if it makes sense or is out of scope here (I don't believe it is, since if the interface is being exposed, it may be worth rethinking how it is layered if it's to be exposed through LLVMSupport headers).

It sounds like the scenario you're describing could be handled by just having a custom VFS implementation. What part of the RedirectingFileSystem would you repurpose for this? The reason I want to move it into the header is because I actually need the YAML stuff for LLDB's reproducers.

[JDevlieghere]

post-holiday ping

[sammccall]

This looks reasonable to me, thanks! Just questions about what's exposed where.
(Apologies, was out for all of december and just got back)

include/llvm/Support/VirtualFileSystem.h

503

Entry and EntryKind don't seem to apply to anything other than RedirectingVFS, so I think they could be nested within RedirectingVFS or at least given names tying them to that class (rather than to VFS itself)

534

Unrelated/unused?

631

does this stuff need to be protected rather than private? I can't find any subclasses

[JDevlieghere]

In D54277#1349694, @sammccall wrote:

This looks reasonable to me, thanks! Just questions about what's exposed where.
(Apologies, was out for all of december and just got back)

No worries, thanks for having a look!

I moved the classes and enum into the RedirectingFileSystem.

[JDevlieghere]

include/llvm/Support/VirtualFileSystem.h

534

Ah, this is needed for the LLDB reproducers. I'll split it off into a separate patch.

[sammccall]

(Really sorry, I thought I'd accepted this on the previous iteration)

[JDevlieghere]

In D54277#1357735, @sammccall wrote:

(Really sorry, I thought I'd accepted this on the previous iteration)

No worries & thank you!

include/llvm/Support/VirtualFileSystem.h

public:
   openFileForRead(const Twine &Path) = 0;
 
   /// This is a convenience method that opens a file, gets its content and then
   /// closes the file.
   llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
   getBufferForFile(const Twine &Name, int64_t FileSize = -1,
                    bool RequiresNullTerminator = true, bool IsVolatile = false);
 
+  virtual llvm::Optional<std::string> getExternalPath(const Twine &Path) {
+    return llvm::None;
+  }
+
   /// Get a directory_iterator for \p Dir.
   /// \note The 'end' iterator is directory_iterator().
   virtual directory_iterator dir_begin(const Twine &Dir,
                                        std::error_code &EC) = 0;
 
   /// Set the working directory. This will affect all following operations on
   /// this file system and may propagate down for nested file systems.
   virtual std::error_code setCurrentWorkingDirectory(const Twine &Path) = 0;
public:
   OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);
 
   /// Pushes a file system on top of the stack.
   void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);
 
   llvm::ErrorOr<Status> status(const Twine &Path) override;
   llvm::ErrorOr<std::unique_ptr<File>>
   openFileForRead(const Twine &Path) override;
+  llvm::Optional<std::string> getExternalPath(const Twine &Path) override;
   directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
   llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override;
   std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
   std::error_code isLocal(const Twine &Path, bool &Result) override;
   std::error_code getRealPath(const Twine &Path,
                               SmallVectorImpl<char> &Output) const override;
 
   using iterator = FileSystemList::reverse_iterator;

 class ProxyFileSystem : public FileSystem {
 public:
   explicit ProxyFileSystem(IntrusiveRefCntPtr<FileSystem> FS)
       : FS(std::move(FS)) {}
 
   llvm::ErrorOr<Status> status(const Twine &Path) override {
     return FS->status(Path);
   }
+  llvm::Optional<std::string> getExternalPath(const Twine &Path) override {
+    return FS->getExternalPath(Path);
+  }
   llvm::ErrorOr<std::unique_ptr<File>>
   openFileForRead(const Twine &Path) override {
     return FS->openFileForRead(Path);
   }
   directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override {
     return FS->dir_begin(Dir, EC);
   }
   llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {
struct YAMLVFSEntry {
   YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
       : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)) {}
   std::string VPath;
   std::string RPath;
 };
 
 /// Collect all pairs of <virtual path, real path> entries from the
 /// \p YAMLFilePath. This is used by the module dependency collector to forward
 /// the entries into the reproducer output VFS YAML file.
 void collectVFSFromYAML(
     std::unique_ptr<llvm::MemoryBuffer> Buffer,
     llvm::SourceMgr::DiagHandlerTy DiagHandler, StringRef YAMLFilePath,
     SmallVectorImpl<YAMLVFSEntry> &CollectedEntries,
     void *DiagContext = nullptr,
     IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
 
 class YAMLVFSWriter {
public:
 
   void setUseExternalNames(bool UseExtNames) { UseExternalNames = UseExtNames; }
 
   void setOverlayDir(StringRef OverlayDirectory) {
     IsOverlayRelative = true;
     OverlayDir.assign(OverlayDirectory.str());
   }
 
   void write(llvm::raw_ostream &OS);
 };
 
 } // namespace vfs
 } // namespace llvm
 
 #endif // LLVM_SUPPORT_VIRTUALFILESYSTEM_H

lib/Support/VirtualFileSystem.cpp

 
 /// The file system according to your operating system.
 class RealFileSystem : public FileSystem {
 public:
   ErrorOr<Status> status(const Twine &Path) override;
   ErrorOr<std::unique_ptr<File>> openFileForRead(const Twine &Path) override;
   directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
 
+  llvm::Optional<std::string> getExternalPath(const Twine &Path) override;
   llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override;
   std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
   std::error_code isLocal(const Twine &Path, bool &Result) override;
   std::error_code getRealPath(const Twine &Path,
                               SmallVectorImpl<char> &Output) const override;
 
 private:
   mutable std::mutex CWDMutex;

 }
 
 std::error_code
 RealFileSystem::getRealPath(const Twine &Path,
                             SmallVectorImpl<char> &Output) const {
   return llvm::sys::fs::real_path(Path, Output);
 }
 
+llvm::Optional<std::string> RealFileSystem::getExternalPath(const Twine &Path) {
+  return Path.str();
+}
+
 IntrusiveRefCntPtr<FileSystem> vfs::getRealFileSystem() {
   static IntrusiveRefCntPtr<FileSystem> FS = new RealFileSystem();
   return FS;
 }
 
 namespace {
 
 class RealFSDirIter : public llvm::vfs::detail::DirIterImpl {
OverlayFileSystem::openFileForRead(const llvm::Twine &Path) {
   for (iterator I = overlays_begin(), E = overlays_end(); I != E; ++I) {
     auto Result = (*I)->openFileForRead(Path);
     if (Result || Result.getError() != llvm::errc::no_such_file_or_directory)
       return Result;
   }
   return make_error_code(llvm::errc::no_such_file_or_directory);
 }
 
+Optional<std::string> OverlayFileSystem::getExternalPath(const Twine &Path) {
+  for (auto &FS : FSList)
+    if (FS->exists(Path))
+      return FS->getExternalPath(Path);
+  return llvm::None;
+}
+
 llvm::ErrorOr<std::string>
 OverlayFileSystem::getCurrentWorkingDirectory() const {
   // All file systems are synchronized, just take the first working directory.
   return FSList.front()->getCurrentWorkingDirectory();
 }
 
 std::error_code
 OverlayFileSystem::setCurrentWorkingDirectory(const Twine &Path) {
public:
   /// returns a virtual file system representing its contents.
   static RedirectingFileSystem *
   create(std::unique_ptr<MemoryBuffer> Buffer,
          SourceMgr::DiagHandlerTy DiagHandler, StringRef YAMLFilePath,
          void *DiagContext, IntrusiveRefCntPtr<FileSystem> ExternalFS);
 
   ErrorOr<Status> status(const Twine &Path) override;
   ErrorOr<std::unique_ptr<File>> openFileForRead(const Twine &Path) override;
+  Optional<std::string> getExternalPath(const Twine &Path) override;
 
   llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {
     return ExternalFS->getCurrentWorkingDirectory();
   }
 
   std::error_code setCurrentWorkingDirectory(const Twine &Path) override {
     return ExternalFS->setCurrentWorkingDirectory(Path);
   }
RedirectingFileSystem::openFileForRead(const Twine &Path) {
 
   // FIXME: Update the status with the name and VFSMapped.
   Status S = getRedirectedFileStatus(Path, F->useExternalName(UseExternalNames),
                                      *ExternalStatus);
   return std::unique_ptr<File>(
       llvm::make_unique<FileWithFixedStatus>(std::move(*Result), S));
 }
 
+Optional<std::string>
+RedirectingFileSystem::getExternalPath(const Twine &Path) {
+  ErrorOr<Entry *> E = lookupPath(Path);
+  if (!E) {
+    if (IsFallthrough &&
+        E.getError() == llvm::errc::no_such_file_or_directory) {
+      return Path.str();
+    }
+    return llvm::None;
+  }
+
+  auto *F = dyn_cast<RedirectingFileEntry>(*E);
+  if (!F)
+    return llvm::None;
+
+  return F->getExternalContentsPath().str();
+}
+
 IntrusiveRefCntPtr<FileSystem>
 vfs::getVFSFromYAML(std::unique_ptr<MemoryBuffer> Buffer,
                     SourceMgr::DiagHandlerTy DiagHandler,
                     StringRef YAMLFilePath, void *DiagContext,
                     IntrusiveRefCntPtr<FileSystem> ExternalFS) {
   return RedirectingFileSystem::create(std::move(Buffer), DiagHandler,
                                        YAMLFilePath, DiagContext,
                                        std::move(ExternalFS));

unittests/Support/VirtualFileSystemTest.cpp

IntrusiveRefCntPtr<vfs::FileSystem> FS = getFromYAMLString(
       "}",
       Lower);
   ASSERT_TRUE(FS.get() != nullptr);
 
   std::error_code EC;
   checkContents(FS->dir_begin("//root/foo", EC),
                 {"//root/foo/a", "//root/foo/b"});
 }
+
+TEST_F(VFSFromYAMLTest, ExternalPath) {
+  ScopedDir TestDirectory("virtual-file-system-test", /*Unique*/ true);
+  ScopedDir _a(TestDirectory + "/a");
+  ScopedDir _b(TestDirectory + "/b");
+
+  IntrusiveRefCntPtr<vfs::FileSystem> RealFS = vfs::getRealFileSystem();
+
+  std::string Root = StringRef(TestDirectory).str();
+  // clang-format off
+  std::string Yaml = "{ 'roots': [\n"
+                     "{\n"
+                     "  'type': 'directory',\n"
+                     "  'name': '/',\n"
+                     "  'contents': [ {\n"
+                     "                  'type': 'file',\n"
+                     "                  'name': 'foo',\n"
+                     "                  'external-contents': '"+ Root +"/a'\n"
+                     "                },\n"
+                     "                {\n"
+                     "                  'type': 'file',\n"
+                     "                  'name': 'bar',\n"
+                     "                  'external-contents': '"+ Root +"/b'\n"
+                     "                }\n"
+                     "              ]\n"
+                     "}\n"
+                     "]\n"
+                     "}";
+  // clang-format on
+
+  IntrusiveRefCntPtr<vfs::FileSystem> FS = getFromYAMLString(Yaml, RealFS);
+  ASSERT_TRUE(FS.get() != nullptr);
+
+  auto A = FS->getExternalPath("/foo");
+  ASSERT_TRUE(A);
+  ASSERT_EQ(Root + "/a", *A);
+
+  auto B = FS->getExternalPath("/bar");
+  ASSERT_TRUE(B);
+  ASSERT_EQ(Root + "/b", *B);
+}